turbo-editors/turbo-js · use-snippets.md

⑂ v1.0.0

use-snippets.md · 99 lines · 4.2 KBmarkdown    Blame HistoryRaw
   1# How to insert snippets from a menu
3This guide shows how to set up reusable pieces of text and put them into a file at the cursor. It assumes Turbo JS is already installed.
5## Get a starter file
7Start the editor **from the project's own directory**, then choose **Snippets ▸ Create snippets file** (`Alt-N`, then `C`).
9That writes `.turbo-js/snippets.toml`, filled in with a handful of JavaScript constructs, one for `package.json` and a couple of general ones, and opens it — coloured, because Turbo JS colours TOML:
12[[snippet]]
13name = "for of"
14group = "JavaScript"
15languages = ["javascript"]
16
17for (const item of items) {
20[[snippet]]
21group = "General"
22name = "Hello"
23body = "Hello!!!"
26Each `[[snippet]]` becomes one line of the menu. The file is read every time the menu opens, so editing it takes effect immediately — no restart.
28## Insert one
30Open **Snippets** (`Alt-N`). Snippets sharing a `group` appear together in a submenu of that name; one with no group goes into **General**.
32| Key | Effect |
33| --- | --- |
34| `Alt-N`, or `F10` then `→` to Snippets | Open the menu |
35| `↑` `↓` | Move down the groups |
36| `→`, or `Enter` | Open the highlighted group |
37| `↑` `↓` then `Enter` | Insert the highlighted snippet |
38| `←` | Back out of a group |
39| `Escape` | Put the whole menu away |
41The 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:
44function main() {
45  |                              ← cursor here
49becomes, after **JavaScript ▸ for of**,
52function main() {
53  for (const item of items) {
58It is one undo step: `Ctrl-Z` takes the whole snippet back out.
60## Keep snippets across every project
62Put them in `~/.config/turbo-js/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.
64Where 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.
66## Show a snippet only where it makes sense
68Add `languages`, using the names the editor uses — `javascript`, `json`, `toml`, `yaml`, `markdown`, `html`, `xml`, `dockerfile`, `bash`:
71[[snippet]]
72name = "strict mode"
73group = "Shell"
74languages = ["bash"]
75body = "set -euo pipefail"
78That 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`.
80A group left with nothing after filtering does not appear at all.
82## Write a JavaScript body
84Two habits, the first taken from the starter file:
86- **Indent with two spaces.** It is what Prettier writes by default, so a tab in a body would be reformatted away the first time `npx prettier --write .` runs — a diff nobody asked for.
87- **Use a literal string** — `'''…'''`, single quotes — for any body with a backslash in it. A JavaScript 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: `console.log("caught: \"" + e + "\"")` would arrive with real quotation marks in it and no longer parse. Inside `'''` a backslash is just a backslash.
89## Variants
91- **You started the editor from a subdirectory.** The project's file is not found: only `./.turbo-js` is looked at, the same rule `settings.toml` follows. Your own snippets still appear.
92- **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.
93- **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.
95## See also
97- Every key of the file and every rule: [Snippets reference](../reference/snippets.md)
98- Why the menu is rebuilt each time it opens, why insertion re-indents, and why the JavaScript bodies indent two spaces: [Snippets](../explanation/snippets.md)
99- The other file in `.turbo-js`: [Project settings](../reference/project-settings.md)

📦 Turbo JS 91999d1 k33g 12h ago	1	# How to insert snippets from a menu
	2
	3	This guide shows how to set up reusable pieces of text and put them into a file at the cursor. It assumes Turbo JS is already installed.
	4
	5	## Get a starter file
	6
	7	Start the editor from the project's own directory, then choose Snippets ▸ Create snippets file (`Alt-N`, then `C`).
	8
	9	That writes `.turbo-js/snippets.toml`, filled in with a handful of JavaScript constructs, one for `package.json` and a couple of general ones, and opens it — coloured, because Turbo JS colours TOML:
	10
	11	```toml
	12	[[snippet]]
	13	name = "for of"
	14	group = "JavaScript"
	15	languages = ["javascript"]
	16	body = """
	17	for (const item of items) {
	18	}"""
	19
	20	[[snippet]]
	21	group = "General"
	22	name = "Hello"
	23	body = "Hello!!!"
	24	```
	25
	26	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.
	27
	28	## Insert one
	29
	30	Open Snippets (`Alt-N`). Snippets sharing a `group` appear together in a submenu of that name; one with no group goes into General.
	31
	32	\| Key \| Effect \|
	33	\| --- \| --- \|
	34	\| `Alt-N`, or `F10` then `→` to Snippets \| Open the menu \|
	35	\| `↑` `↓` \| Move down the groups \|
	36	\| `→`, or `Enter` \| Open the highlighted group \|
	37	\| `↑` `↓` then `Enter` \| Insert the highlighted snippet \|
	38	\| `←` \| Back out of a group \|
	39	\| `Escape` \| Put the whole menu away \|
	40
	41	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:
	42
	43	```
	44	function main() {
	45	\| ← cursor here
	46	}
	47	```
	48
	49	becomes, after JavaScript ▸ for of,
	50
	51	```
	52	function main() {
	53	for (const item of items) {
	54	}
	55	}
	56	```
	57
	58	It is one undo step: `Ctrl-Z` takes the whole snippet back out.
	59
	60	## Keep snippets across every project
	61
	62	Put them in `~/.config/turbo-js/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.
	63
	64	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.
65
66	## Show a snippet only where it makes sense
67
68	Add `languages`, using the names the editor uses — `javascript`, `json`, `toml`, `yaml`, `markdown`, `html`, `xml`, `dockerfile`, `bash`:
69
70	```toml
71	[[snippet]]
72	name = "strict mode"
73	group = "Shell"
74	languages = ["bash"]
75	body = "set -euo pipefail"
76	```
77
78	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`.
79
80	A group left with nothing after filtering does not appear at all.
81
82	## Write a JavaScript body
83
84	Two habits, the first taken from the starter file:
85
86	- Indent with two spaces. It is what Prettier writes by default, so a tab in a body would be reformatted away the first time `npx prettier --write .` runs — a diff nobody asked for.
87	- Use a literal string — `'''…'''`, single quotes — for any body with a backslash in it. A JavaScript 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: `console.log("caught: \"" + e + "\"")` would arrive with real quotation marks in it and no longer parse. Inside `'''` a backslash is just a backslash.
88
89	## Variants
90
91	- You started the editor from a subdirectory. The project's file is not found: only `./.turbo-js` is looked at, the same rule `settings.toml` follows. Your own snippets still appear.
92	- 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.
93	- 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.
94
95	## See also
96
97	- Every key of the file and every rule: [Snippets reference](../reference/snippets.md)
98	- Why the menu is rebuilt each time it opens, why insertion re-indents, and why the JavaScript bodies indent two spaces: [Snippets](../explanation/snippets.md)
99	- The other file in `.turbo-js`: [Project settings](../reference/project-settings.md)