| 📦 Turbo JS 91999d1 k33g 11h ago | 1 | # Référence : snippets |
| 2 | |
| 3 | > Description neutre des fichiers de snippets, du menu Snippets, et de la façon dont un snippet est inséré. |
| 4 | |
| 5 | ## Fichiers |
| 6 | |
| 7 | Les deux sont lus, et les deux sont facultatifs. |
| 8 | |
| 9 | | Fichier | Contient | |
| 10 | | --- | --- | |
| 11 | | `./.turbo-js/snippets.toml` | Les snippets du projet | |
| 12 | | `$TURBO_JS_SNIPPET_DIR/snippets.toml`, sinon `<config utilisateur>/turbo-js/snippets.toml` | Les vôtres, partagés entre projets | |
| 13 | |
| 14 | `<config utilisateur>` est `os.UserConfigDir()` : `~/.config` sous Linux, `~/Library/Application Support` sous macOS. `TURBO_JS_DIR` remplace `<config utilisateur>/turbo-js` en entier. |
| 15 | |
| 16 | | Propriété | Valeur | |
| 17 | | --- | --- | |
| 18 | | Recherche du projet | Le répertoire de travail seulement. Les dossiers parents ne sont **pas** parcourus. | |
| 19 | | Lecture | À chaque ouverture du menu Snippets | |
| 20 | | Ordre | Les vôtres d'abord, puis ceux du projet | |
| 21 | | Conflit de nom | Même `group` **et** même `name` → celui du projet remplace le vôtre | |
| 22 | | Fichier absent | Pas une erreur | |
| 23 | | Fichier illisible | Une erreur, signalée dans le menu | |
| 24 | |
| 25 | ## Format du fichier |
| 26 | |
| 27 | Une table `[[snippet]]` par snippet. |
| 28 | |
| 29 | | Clé | Type | Obligatoire | Description | |
| 30 | | --- | --- | --- | --- | |
| 31 | | `name` | chaîne | oui | Ce que le menu affiche | |
| 32 | | `body` | chaîne | oui | Le texte inséré au curseur | |
| 33 | | `group` | chaîne | non | Le sous-menu où il va ; absent signifie `General` | |
| 34 | | `languages` | tableau de chaînes | non | Restreint le snippet à ces langages ; absent signifie tous les fichiers | |
| 35 | |
| 36 | `languages` emploie les noms de langages de l'éditeur : `javascript`, `json`, `toml`, `yaml`, `markdown`, `html`, `xml`, `dockerfile`, `bash`. Voir [Langages colorés](languages.md). |
| 37 | |
| 38 | Un snippet sans `name` ou sans `body` rend tout le fichier erroné — il n'aurait pu être affiché, ou n'aurait rien à insérer. |
| 39 | |
| 40 | ### Exemple |
| 41 | |
| 42 | ```toml |
| 43 | [[snippet]] |
| 44 | name = "for of" |
| 45 | group = "JavaScript" |
| 46 | languages = ["javascript"] |
| 47 | body = """ |
| 48 | for (const item of items) { |
| 49 | }""" |
| 50 | ``` |
| 51 | |
| 52 | Les chaînes multi-lignes du TOML — `'''…'''` comme `"""…"""` — suppriment le saut de ligne qui suit immédiatement les guillemets d'ouverture. Dans une chaîne **basique** (`"""`), `\t` devient une tabulation et `\"` un guillemet à la lecture du fichier ; dans une chaîne **littérale** (`'''`), rien n'est interprété. Les corps de plusieurs lignes du fichier de départ sont des chaînes basiques — un guillemet JavaScript, `"node:test"`, y passe sans échappement — et les corps d'une ligne qui portent des guillemets doubles sont écrits entre apostrophes, `'…'`. |
| 53 | |
| 54 | ## Le fichier de départ |
| 55 | |
| 56 | **Create snippets file** écrit un fichier commenté contenant : |
| 57 | |
| 58 | | Groupe | `languages` | Snippets | |
| 59 | | --- | --- | --- | |
| 60 | | JavaScript | `["javascript"]` | `import`, `require`, `async function`, `try / catch`, `class`, `for of`, `test` | |
| 61 | | JSON | `["json"]` | `scripts` | |
| 62 | | General | aucun | `Hello` | |
| 63 | | Markdown | `["markdown"]` | `Image` | |
| 64 | |
| 65 | Les corps JavaScript sont indentés de deux espaces, ce que Prettier écrit par défaut ; une tabulation serait reformatée au premier `npx prettier --write`. |
| 66 | |
| 67 | ## Le menu |
| 68 | |
| 69 | | Entrée | Condition | |
| 70 | | --- | --- | |
| 71 | | Un sous-menu par groupe, dans l'ordre d'apparition des groupes dans les fichiers | Un groupe ayant au moins un snippet applicable à la fenêtre au premier plan | |
| 72 | | `Cannot read snippets`, grisé | Un fichier est présent mais illisible | |
| 73 | | `Create snippets file` | Le projet n'a pas de fichier de snippets | |
| 74 | | `Open snippets file` | Le projet en a un | |
| 75 | |
| 76 | La touche chaude du menu est `Alt-N`, pas `Alt-S` : Search répond déjà au S. |
| 77 | |
| 78 | Les groupes, et les snippets à l'intérieur, sortent dans l'ordre de lecture : le menu correspond aux fichiers. |
| 79 | |
| 80 | Une entrée de snippet est grisée quand aucun fichier n'est ouvert pour l'y insérer — un terminal ou l'arbre du projet au premier plan compte comme aucun fichier. |
| 81 | |
| 82 | ### Filtrage |
| 83 | |
| 84 | | Fenêtre au premier plan | Snippets proposés | |
| 85 | | --- | --- | |
| 86 | | Un fichier d'un langage reconnu | Ceux qui nomment ce langage, plus ceux qui n'en nomment aucun | |
| 87 | | Un fichier d'aucun langage reconnu | Ceux qui n'en nomment aucun | |
| 88 | | Un terminal, l'arbre du projet, ou rien | Ceux qui n'en nomment aucun | |
| 89 | |
| 90 | Un fichier `.js`, `.mjs` ou `.cjs` est de langue `javascript` ; de même un fichier sans extension dont la première ligne est un shebang nommant `node`. Un fichier `.json` ou `.jsonc` est de langue `json`. |
| 91 | |
| 92 | ## Insertion |
| 93 | |
| 94 | | Comportement | Détail | |
| 95 | | --- | --- | |
| 96 | | Position | Au curseur | |
| 97 | | Première ligne | Insérée là où est le curseur | |
| 98 | | Lignes suivantes | Préfixées par l'indentation de la ligne où était le curseur | |
| 99 | | Lignes vides du corps | Laissées vides, non complétées d'espaces | |
| 100 | | Annulation | Une seule opération pour tout le snippet | |
| 101 | | Curseur ensuite | À la fin du texte inséré | |
| 102 | | Signalement | `Snippet inserted` dans la barre d'état | |
| 103 | |
| 104 | L'indentation copiée est le **préfixe d'espaces de la ligne courante**, tabulations ou espaces telles quelles : un snippet suit donc ce que le fichier emploie déjà. |
| 105 | |
| 106 | ## Entrées de menu |
| 107 | |
| 108 | | Entrée | Menu | Effet | |
| 109 | | --- | --- | --- | |
| 110 | | Create snippets file | Snippets | Écrit `.turbo-js/snippets.toml` avec les exemples ci-dessus, puis l'ouvre. Grisée dès que le projet en a un. | |
| 111 | | Open snippets file | Snippets | Ouvre `.turbo-js/snippets.toml`. Grisée tant que le projet n'en a pas. Toujours le fichier du projet, jamais le vôtre — c'est celui qu'écrit l'entrée au-dessus. | |
| 112 | |
| 113 | Le fichier est écrit via un fichier temporaire du même dossier, renommé en place : une écriture interrompue laisse le fichier précédent intact. |
| 114 | |
| 115 | ## Erreurs |
| 116 | |
| 117 | | Message | Cause | |
| 118 | | --- | --- | |
| 119 | | `Cannot read snippets` dans le menu | Un fichier de snippets est présent mais n'est pas du TOML valide, ou contient un snippet sans nom ou sans corps | |
| 120 | | `Already there: .turbo-js/snippets.toml` | Créer dans un projet qui en a déjà un. Inatteignable depuis le menu, qui grise l'entrée ; reste possible pour un appelant qui n'est pas un menu. | |
| 121 | | `This project has no .turbo-js/snippets.toml yet.` | Ouvrir dans un projet qui n'en a pas, de même | |
| 122 | | `Cannot tell which directory this is: …` | Le répertoire de travail n'a pas pu être lu | |
| 123 | |
| 124 | ## Voir aussi |
| 125 | |
| 126 | - [Insérer des snippets depuis un menu](../how-to/use-snippets.md) |
| 127 | - [Snippets](../explanation/snippets.md) |
| 128 | - [Clavier](keyboard.md) |