turbo-editors/turbo-js · snippets.md

⑂ v1.0.2

snippets.md · 130 lines · 5.4 KBmarkdown    Blame HistoryRaw
   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-js/snippets.toml` | The project's snippets |
12| `$TURBO_JS_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-js/snippets.toml` | Your own, shared across projects |
14`<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS. `TURBO_JS_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: `javascript`, `json`, `toml`, `yaml`, `markdown`, `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 / catch"
45group = "JavaScript"
46languages = ["javascript"]
47
49} catch (error) {
50  console.error(error);
54TOML's `"""` basic strings drop the newline immediately after the opening quotes, and resolve `\t`, `\n` and `\"` before the editor sees them. A body that has to keep a backslash as it is written — a regular expression, or a string carrying `\n` — belongs in a `'''` literal string, which drops that first newline too and keeps every backslash.
56## The starter file
58**Snippets ▸ Create snippets file** writes ten snippets:
60| Group | Names | `languages` |
61| --- | --- | --- |
62| JavaScript | `import`, `require`, `async function`, `try / catch`, `class`, `for of`, `test` | `["javascript"]` |
63| JSON | `scripts` | `["json"]` |
64| General | `Hello` | none |
65| Markdown | `Image` | `["markdown"]` |
67The JavaScript bodies are indented with two spaces, which is what Prettier writes by default.
69## The menu
71| Item | Condition |
72| --- | --- |
73| 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 |
74| `Cannot read snippets`, greyed out | A file is present but unreadable |
75| `Create snippets file` | The project has no snippets file |
76| `Open snippets file` | The project has one |
78The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S.
80Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files.
82A 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.
84### Filtering
86| Front window | Snippets offered |
87| --- | --- |
88| A file of a recognised language | Those naming that language, plus those naming none |
89| A file of no recognised language | Those naming none |
90| A terminal, the project tree, or nothing | Those naming none |
92A `.js` file is of language `javascript`; so is a file with no extension whose first line is a shebang naming `node`.
94## Insertion
96| Behaviour | Detail |
97| --- | --- |
98| Position | At the cursor |
99| First line | Inserted where the cursor is |
100| Later lines | Prefixed with the leading whitespace of the line the cursor was on |
101| Blank lines in the body | Left blank, not padded with whitespace |
102| Undo | One step for the whole snippet |
103| Cursor after | At the end of the inserted text |
104| Report | `Snippet inserted` on the status bar |
106The 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.
108## Menu items
110| Item | Menu | Effect |
111| --- | --- | --- |
112| Create snippets file | Snippets | Writes `.turbo-js/snippets.toml` with the starter snippets above, then opens it. Greyed out once the project has one. |
113| Open snippets file | Snippets | Opens `.turbo-js/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. |
115The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
117
119| Message | Cause |
120| --- | --- |
121| `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 |
122| `Already there: .turbo-js/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. |
123| `This project has no .turbo-js/snippets.toml yet.` | Opening in a project that has none, likewise |
124| `Cannot tell which directory this is: …` | The working directory could not be read |
126## See also
128- [How to insert snippets from a menu](../how-to/use-snippets.md)
129- [Snippets](../explanation/snippets.md)
130- [Keyboard](keyboard.md)

📦 Turbo JS 91999d1 k33g 12h ago	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-js/snippets.toml` \| The project's snippets \|
	12	\| `$TURBO_JS_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-js/snippets.toml` \| Your own, shared across projects \|
	13
	14	`<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS. `TURBO_JS_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: `javascript`, `json`, `toml`, `yaml`, `markdown`, `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 / catch"
	45	group = "JavaScript"
	46	languages = ["javascript"]
	47	body = """
	48	try {
	49	} catch (error) {
	50	console.error(error);
	51	}"""
	52	```
	53
	54	TOML's `"""` basic strings drop the newline immediately after the opening quotes, and resolve `\t`, `\n` and `\"` before the editor sees them. A body that has to keep a backslash as it is written — a regular expression, or a string carrying `\n` — belongs in a `'''` literal string, which drops that first newline too and keeps every backslash.
	55
	56	## The starter file
	57
	58	Snippets ▸ Create snippets file writes ten snippets:
	59
	60	\| Group \| Names \| `languages` \|
	61	\| --- \| --- \| --- \|
	62	\| JavaScript \| `import`, `require`, `async function`, `try / catch`, `class`, `for of`, `test` \| `["javascript"]` \|
	63	\| JSON \| `scripts` \| `["json"]` \|
	64	\| General \| `Hello` \| none \|
65	\| Markdown \| `Image` \| `["markdown"]` \|
66
67	The JavaScript bodies are indented with two spaces, which is what Prettier writes by default.
68
69	## The menu
70
71	\| Item \| Condition \|
72	\| --- \| --- \|
73	\| 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 \|
74	\| `Cannot read snippets`, greyed out \| A file is present but unreadable \|
75	\| `Create snippets file` \| The project has no snippets file \|
76	\| `Open snippets file` \| The project has one \|
77
78	The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S.
79
80	Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files.
81
82	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.
83
84	### Filtering
85
86	\| Front window \| Snippets offered \|
87	\| --- \| --- \|
88	\| A file of a recognised language \| Those naming that language, plus those naming none \|
89	\| A file of no recognised language \| Those naming none \|
90	\| A terminal, the project tree, or nothing \| Those naming none \|
91
92	A `.js` file is of language `javascript`; so is a file with no extension whose first line is a shebang naming `node`.
93
94	## Insertion
95
96	\| Behaviour \| Detail \|
97	\| --- \| --- \|
98	\| Position \| At the cursor \|
99	\| First line \| Inserted where the cursor is \|
100	\| Later lines \| Prefixed with the leading whitespace of the line the cursor was on \|
101	\| Blank lines in the body \| Left blank, not padded with whitespace \|
102	\| Undo \| One step for the whole snippet \|
103	\| Cursor after \| At the end of the inserted text \|
104	\| Report \| `Snippet inserted` on the status bar \|
105
106	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.
107
108	## Menu items
109
110	\| Item \| Menu \| Effect \|
111	\| --- \| --- \| --- \|
112	\| Create snippets file \| Snippets \| Writes `.turbo-js/snippets.toml` with the starter snippets above, then opens it. Greyed out once the project has one. \|
113	\| Open snippets file \| Snippets \| Opens `.turbo-js/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. \|
114
115	The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.
116
117	## Errors
118
119	\| Message \| Cause \|
120	\| --- \| --- \|
121	\| `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 \|
122	\| `Already there: .turbo-js/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. \|
123	\| `This project has no .turbo-js/snippets.toml yet.` \| Opening in a project that has none, likewise \|
124	\| `Cannot tell which directory this is: …` \| The working directory could not be read \|
125
126	## See also
127
128	- [How to insert snippets from a menu](../how-to/use-snippets.md)
129	- [Snippets](../explanation/snippets.md)
130	- [Keyboard](keyboard.md)