turbo-editors/turbo-golo · snippets.md

⑂ v1.0.3

snippets.md · 132 lines · 5.4 KBmarkdown    Blame HistoryRaw
📦 Turbo Golo   1# Reference: snippets
3> Neutral description of the snippets files, the Snippets menu, and how a snippet is inserted.
7Both are read, and both are optional.
9| File | Holds |
10| --- | --- |
11| `./.turbo-golo/snippets.toml` | The project's snippets |
12| `$TURBO_GOLO_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-golo/snippets.toml` | Your own, shared across projects |
14`<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS. `TURBO_GOLO_DIR` replaces it when set.
16| Property | Value |
17| --- | --- |
18| Project search | The working directory only. Parent directories are **not** searched. |
19| Read | Every time the Snippets menu opens |
20| Order | Your own first, then the project's |
21| Name clash | Same `group` **and** `name` → the project's replaces yours |
22| Missing file | Not an error |
23| Unreadable file | An error, shown in the menu |
25## File format
27One `[[snippet]]` table per snippet.
29| Key | Type | Required | Description |
30| --- | --- | --- | --- |
31| `name` | string | yes | What the menu shows |
32| `body` | string | yes | The text inserted at the cursor |
33| `group` | string | no | The submenu it goes in; absent means `General` |
34| `languages` | array of strings | no | Restricts the snippet to those languages; absent means every file |
36`languages` uses the editor's own language names: `golo`, `toml`, `yaml`, `markdown`, `javascript`, `html`, `xml`, `dockerfile`, `bash`. See [Languages coloured](languages.md).
38A snippet with no `name` or no `body` makes the whole file an error — it could not be shown or could not be inserted.
40### Example
43[[snippet]]
44name = "try"
45group = "Golo"
46languages = ["golo"]
47
49  throw "boom"
50} catch (e) {
51  println("caught: \"" + e + "\"")
52} finally {
53  println("done")
57TOML'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.
59## The starter file
61**Snippets ▸ Create snippets file** writes fourteen snippets:
63| Group | Names | `languages` |
64| --- | --- | --- |
65| Golo | `module`, `main`, `function`, `closure`, `struct`, `union`, `augment`, `match`, `foreach`, `for`, `try`, `comprehension` | `["golo"]` |
66| General | `Hello` | none |
67| Markdown | `Image` | `["markdown"]` |
69The Golo bodies are indented with two spaces and written as literal strings.
71## The menu
73| Item | Condition |
74| --- | --- |
75| 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 |
76| `Cannot read snippets`, greyed out | A file is present but unreadable |
77| `Create snippets file` | The project has no snippets file |
78| `Open snippets file` | The project has one |
80The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S.
82Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files.
84A 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.
86### Filtering
88| Front window | Snippets offered |
89| --- | --- |
90| A file of a recognised language | Those naming that language, plus those naming none |
91| A file of no recognised language | Those naming none |
92| A terminal, the project tree, or nothing | Those naming none |
94A `.golo` file is of language `golo`; so is a file with no extension whose first line is a shebang naming `golo`.
96## Insertion
98| Behaviour | Detail |
99| --- | --- |
100| Position | At the cursor |
101| First line | Inserted where the cursor is |
102| Later lines | Prefixed with the leading whitespace of the line the cursor was on |
103| Blank lines in the body | Left blank, not padded with whitespace |
104| Undo | One step for the whole snippet |
105| Cursor after | At the end of the inserted text |
106| Report | `Snippet inserted` on the status bar |
108The 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.
110## Menu items
112| Item | Menu | Effect |
113| --- | --- | --- |
114| Create snippets file | Snippets | Writes `.turbo-golo/snippets.toml` with the starter snippets above, then opens it. Greyed out once the project has one. |
115| 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. |
117The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
119
121| Message | Cause |
122| --- | --- |
123| `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 |
124| `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. |
125| `This project has no .turbo-golo/snippets.toml yet.` | Opening in a project that has none, likewise |
126| `Cannot tell which directory this is: …` | The working directory could not be read |
128## See also
130- [How to insert snippets from a menu](../how-to/use-snippets.md)
131- [Snippets](../explanation/snippets.md)
132- [Keyboard](keyboard.md)

📦 Turbo Golo d710c1b k33g yesterday	1	# Reference: snippets
	2
	3	> Neutral description of the snippets files, the Snippets menu, and how a snippet is inserted.
	4
	5	## Files
	6
	7	Both are read, and both are optional.
	8
	9	\| File \| Holds \|
	10	\| --- \| --- \|
	11	\| `./.turbo-golo/snippets.toml` \| The project's snippets \|
	12	\| `$TURBO_GOLO_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-golo/snippets.toml` \| Your own, shared across projects \|
	13
	14	`<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS. `TURBO_GOLO_DIR` replaces it when set.
	15
	16	\| Property \| Value \|
	17	\| --- \| --- \|
	18	\| Project search \| The working directory only. Parent directories are not searched. \|
	19	\| Read \| Every time the Snippets menu opens \|
	20	\| Order \| Your own first, then the project's \|
	21	\| Name clash \| Same `group` and `name` → the project's replaces yours \|
	22	\| Missing file \| Not an error \|
	23	\| Unreadable file \| An error, shown in the menu \|
	24
	25	## File format
	26
	27	One `[[snippet]]` table per snippet.
	28
	29	\| Key \| Type \| Required \| Description \|
	30	\| --- \| --- \| --- \| --- \|
	31	\| `name` \| string \| yes \| What the menu shows \|
	32	\| `body` \| string \| yes \| The text inserted at the cursor \|
	33	\| `group` \| string \| no \| The submenu it goes in; absent means `General` \|
	34	\| `languages` \| array of strings \| no \| Restricts the snippet to those languages; absent means every file \|
	35
	36	`languages` uses the editor's own language names: `golo`, `toml`, `yaml`, `markdown`, `javascript`, `html`, `xml`, `dockerfile`, `bash`. See [Languages coloured](languages.md).
	37
	38	A snippet with no `name` or no `body` makes the whole file an error — it could not be shown or could not be inserted.
	39
	40	### Example
	41
	42	```toml
	43	[[snippet]]
	44	name = "try"
	45	group = "Golo"
	46	languages = ["golo"]
	47	body = '''
	48	try {
	49	throw "boom"
	50	} catch (e) {
	51	println("caught: \"" + e + "\"")
	52	} finally {
	53	println("done")
	54	}'''
	55	```
	56
	57	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.
	58
	59	## The starter file
	60
	61	Snippets ▸ Create snippets file writes fourteen snippets:
	62
	63	\| Group \| Names \| `languages` \|
	64	\| --- \| --- \| --- \|
65	\| Golo \| `module`, `main`, `function`, `closure`, `struct`, `union`, `augment`, `match`, `foreach`, `for`, `try`, `comprehension` \| `["golo"]` \|
66	\| General \| `Hello` \| none \|
67	\| Markdown \| `Image` \| `["markdown"]` \|
68
69	The Golo bodies are indented with two spaces and written as literal strings.
70
71	## The menu
72
73	\| Item \| Condition \|
74	\| --- \| --- \|
75	\| 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 \|
76	\| `Cannot read snippets`, greyed out \| A file is present but unreadable \|
77	\| `Create snippets file` \| The project has no snippets file \|
78	\| `Open snippets file` \| The project has one \|
79
80	The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S.
81
82	Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files.
83
84	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.
85
86	### Filtering
87
88	\| Front window \| Snippets offered \|
89	\| --- \| --- \|
90	\| A file of a recognised language \| Those naming that language, plus those naming none \|
91	\| A file of no recognised language \| Those naming none \|
92	\| A terminal, the project tree, or nothing \| Those naming none \|
93
94	A `.golo` file is of language `golo`; so is a file with no extension whose first line is a shebang naming `golo`.
95
96	## Insertion
97
98	\| Behaviour \| Detail \|
99	\| --- \| --- \|
100	\| Position \| At the cursor \|
101	\| First line \| Inserted where the cursor is \|
102	\| Later lines \| Prefixed with the leading whitespace of the line the cursor was on \|
103	\| Blank lines in the body \| Left blank, not padded with whitespace \|
104	\| Undo \| One step for the whole snippet \|
105	\| Cursor after \| At the end of the inserted text \|
106	\| Report \| `Snippet inserted` on the status bar \|
107
108	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.
109
110	## Menu items
111
112	\| Item \| Menu \| Effect \|
113	\| --- \| --- \| --- \|
114	\| Create snippets file \| Snippets \| Writes `.turbo-golo/snippets.toml` with the starter snippets above, then opens it. Greyed out once the project has one. \|
115	\| 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. \|
116
117	The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
118
119	## Errors
120
121	\| Message \| Cause \|
122	\| --- \| --- \|
123	\| `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 \|
124	\| `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. \|
125	\| `This project has no .turbo-golo/snippets.toml yet.` \| Opening in a project that has none, likewise \|
126	\| `Cannot tell which directory this is: …` \| The working directory could not be read \|
127
128	## See also
129
130	- [How to insert snippets from a menu](../how-to/use-snippets.md)
131	- [Snippets](../explanation/snippets.md)
132	- [Keyboard](keyboard.md)