| 📦 Turbo Go 3d7798b k33g 13h ago | 1 | # Référence : outils go |
| 2 | |
| 3 | > Description neutre de `.turbo-go/tools.toml`, du menu Go, et de ce que lancer une commande fait. |
| 4 | |
| 5 | ## Fichier |
| 6 | |
| 7 | | Propriété | Valeur | |
| 8 | | --- | --- | |
| 9 | | Chemin | `./.turbo-go/tools.toml` | |
| 10 | | Recherche | Le répertoire de travail seulement. Les dossiers parents ne sont **pas** parcourus. | |
| 11 | | Lecture | À chaque ouverture d'un de ses menus, pour les entrées | |
| 12 | | Relecture | Dès que la taille ou la date de modification du fichier change, pour l'**ensemble** des menus | |
| 13 | | Fichier absent | Pas une erreur | |
| 14 | | Fichier illisible | Une erreur, signalée dans le menu | |
| 15 | | Fichier utilisateur | **Aucun.** Contrairement aux snippets, il n'y a pas de `~/.config/turbo-go/tools.toml`. | |
| 16 | |
| 17 | ## Format du fichier |
| 18 | |
| 19 | Une table `[[tool]]` par commande. |
| 20 | |
| 21 | | Clé | Type | Obligatoire | Description | |
| 22 | | --- | --- | --- | --- | |
| 23 | | `name` | chaîne | oui | Ce que le menu affiche. Peut porter une touche d'accès écrite avec des tildes, comme `"~T~est"`. | |
| 24 | | `command` | chaîne | oui | La commande shell à exécuter | |
| 25 | | `output` | chaîne | non | Où va sa sortie : `popup`, `terminal` ou `editor`. Absent signifie `popup`. | |
| 26 | | `menu` | chaîne | non | Dans quel menu il apparaît. Absent signifie `Go`. N'importe quel nom ; le menu est créé pour vous. Peut porter une touche d'accès écrite avec des tildes. | |
| 27 | |
| 28 | `menu` n'est pas vérifié contre une liste, parce qu'il n'y en a pas : un nom qu'aucun autre outil n'emploie crée simplement un menu. Un outil sans `name`, sans `command`, ou dont l'`output` nomme quelque chose qui n'existe pas rend tout le fichier erroné. Un `output` inconnu est **refusé et non corrigé** : `"termnial"` aurait sinon l'air d'avoir fonctionné tout en envoyant la sortie ailleurs. |
| 29 | |
| 30 | ### Exemple |
| 31 | |
| 32 | ```toml |
| 33 | [[tool]] |
| 34 | name = "~T~est" |
| 35 | command = "go test ./..." |
| 36 | output = "popup" |
| 37 | |
| 38 | [[tool]] |
| 39 | name = "~E~cho" |
| 40 | command = "echo TADA" |
| 41 | output = "terminal" |
| 42 | menu = "Tools" |
| 43 | ``` |
| 44 | |
| 45 | ## Le fichier de départ |
| 46 | |
| 47 | **Go ▸ Create tools file** écrit ces cinq, dans cet ordre : |
| 48 | |
| 49 | | Nom | Commande | Sortie | |
| 50 | | --- | --- | --- | |
| 51 | | Format | `gofmt -l -w .` | `popup` | |
| 52 | | Lint | `go vet ./...` | `popup` | |
| 53 | | Build | `go build ./...` | `popup` | |
| 54 | | Test | `go test ./...` | `popup` | |
| 55 | | Run | `go run .` | `terminal` | |
| 56 | |
| 57 | Aucun ne nomme de `menu`, donc les cinq sont dans le menu Go. Chacun nomme son `output`, y compris les quatre qui nomment le défaut : la clé est la partie intéressante du format, et un fichier où elle n'apparaît qu'une fois est un fichier où personne ne remarque qu'elle existe. |
| 58 | |
| 59 | L'entrée est grisée dès que le projet a un fichier d'outils : elle ne peut donc pas en écraser un. Le fichier est écrit via un fichier temporaire du même dossier, renommé en place. |
| 60 | |
| 61 | ## Le menu Go |
| 62 | |
| 63 | Toujours sur la barre, qu'un fichier d'outils existe ou non. Sa touche d'accès est `Alt-G`. |
| 64 | |
| 65 | | Entrée | Condition | |
| 66 | | --- | --- | |
| 67 | | Une ligne par outil sans `menu`, dans l'ordre du fichier | Le fichier en contient au moins un | |
| 68 | | `Cannot read tools`, grisé | Le fichier est présent mais illisible | |
| 69 | | `Create tools file` | Le projet n'a pas de fichier d'outils | |
| 70 | | `Open tools file` | Le projet en a un | |
| 71 | |
| 72 | ## Les menus qu'un outil réclame |
| 73 | |
| 74 | Un `menu` nommant autre chose que `Go` place sur la barre un menu de ce nom. |
| 75 | |
| 76 | | Propriété | Valeur | |
| 77 | | --- | --- | |
| 78 | | Position | Entre Go et Help | |
| 79 | | Ordre | L'ordre où chaque nom apparaît pour la première fois dans le fichier | |
| 80 | | Entrées | Une ligne par outil nommant ce menu, dans l'ordre du fichier. Rien d'autre — `Create tools file` et `Open tools file` restent dans Go. | |
| 81 | | Fichier illisible | Aucun menu ; c'est le menu Go qui porte l'erreur | |
| 82 | | Pendant que l'éditeur tourne | Ajoutés, retirés et renommés au fil des modifications du fichier, sans redémarrage | |
| 83 | |
| 84 | ### Touches d'accès |
| 85 | |
| 86 | Attribuées automatiquement, parce qu'un nom venu d'un fichier ne peut pas être confronté à l'avance aux menus fixes. |
| 87 | |
| 88 | | Cas | Résultat | |
| 89 | | --- | --- | |
| 90 | | Aucun tilde dans le nom | La première lettre qu'aucun autre menu ne revendique est marquée. `Format` devient `For~m~at` : `F` est à File, `o` à Options, `r` à Run. | |
| 91 | | Des tildes nommant une lettre libre | Conservés tels quels. `Doc~k~er` répond à `Alt-K`. | |
| 92 | | Des tildes nommant une lettre prise | Abandonnés, et une lettre libre choisie à la place. `~F~oo` devient `F~o~o`. | |
| 93 | | Toutes les lettres prises | Pas de touche d'accès. `F10` et la souris l'ouvrent quand même. | |
| 94 | |
| 95 | Les lettres que les menus de l'éditeur occupent sont `F`, `E`, `S`, `R`, `O`, `W`, `N` (Snippets), `G` et `H`. |
| 96 | |
| 97 | ## Lancer une commande |
| 98 | |
| 99 | Commun à toutes les sorties : |
| 100 | |
| 101 | | Propriété | Valeur | |
| 102 | | --- | --- | |
| 103 | | Shell | `/bin/sh -c "<commande>"` sous Linux et macOS ; `cmd.exe /S /C "<commande>"` — le shell que nomme `%COMSPEC%` — sous Windows | |
| 104 | | Répertoire | Celui depuis lequel l'éditeur a été lancé | |
| 105 | | Erreur standard | Mêlée à la sortie standard, dans l'ordre où la commande les a écrites | |
| 106 | |
| 107 | Passer par un shell signifie que les tubes, les globs, `&&` et `;` fonctionnent : un outil peut être une séquence. Sous Windows le shell est cmd.exe, qui connaît `&&`, `|` et `>` mais ne développe pas les globs, et où `;` n'est pas un séparateur. |
| 108 | |
| 109 | ### `output = "popup"` |
| 110 | |
| 111 | | Propriété | Valeur | |
| 112 | | --- | --- | |
| 113 | | Ouverture | Immédiate, avant la fin de la commande | |
| 114 | | Modale | Oui : rien d'autre dans l'éditeur n'est utilisable tant qu'elle est là | |
| 115 | | Remplissage | À mesure que la sortie arrive, en la suivant tant qu'on n'a pas remonté | |
| 116 | | Titre pendant | `<commande> — running` | |
| 117 | | Titre à la fin | `<commande> — ok`, ou `<commande> — exit <n>` | |
| 118 | | Sortie vide, terminée | Affiche `(no output)` | |
| 119 | | Sortie vide, en cours | N'affiche rien | |
| 120 | | Plafond de sortie | 10000 lignes ; au-delà les plus anciennes partent et une ligne `… n earlier lines dropped …` le dit | |
| 121 | |
| 122 | | Touche | Effet | |
| 123 | | --- | --- | |
| 124 | | `↑` `↓` `Page↑` `Page↓` `Début` `Fin` | Parcourir la sortie | |
| 125 | | Molette | Idem | |
| 126 | | `Échap`, `Entrée`, **Close** | Fermer, en **arrêtant la commande** si elle tourne encore | |
| 127 | |
| 128 | Fermer arrête la commande parce qu'il n'y a pas d'autre moyen d'interrompre celle dont la sortie n'est pas dans un terminal. |
| 129 | |
| 130 | ### `output = "terminal"` |
| 131 | |
| 132 | | Propriété | Valeur | |
| 133 | | --- | --- | |
| 134 | | Fenêtre | Une fenêtre terminal à elle, titrée avec la commande | |
| 135 | | Environnement | Celui de l'éditeur, avec `TERM` à `xterm-256color` | |
| 136 | | Après la sortie | La fenêtre reste, montrant sa sortie | |
| 137 | | Modale | Non : l'éditeur continue à côté | |
| 138 | |
| 139 | Comme c'est un vrai terminal, les couleurs, la pagination, `Ctrl-C` et la lecture au clavier fonctionnent. Voir [Fenêtres terminal](terminal.md). |
| 140 | |
| 141 | Touches dans une fenêtre **terminée** : |
| 142 | |
| 143 | | Touche | Effet | |
| 144 | | --- | --- | |
| 145 | | `Maj-Page↑`, `Maj-Page↓` | Relire la sortie | |
| 146 | | `Ctrl-W` | Fermer la fenêtre | |
| 147 | | Tout le reste | Atteint l'éditeur, pas le shell mort | |
| 148 | |
| 149 | ### `output = "editor"` |
| 150 | |
| 151 | | Propriété | Valeur | |
| 152 | | --- | --- | |
| 153 | | Affiche | Une popup pendant l'exécution, comme ci-dessus | |
| 154 | | À la fermeture de la popup | Une fenêtre d'édition contenant la sortie, titrée avec la commande | |
| 155 | | Remplie | Une fois, à la fin de la commande — pas au fil de l'eau | |
| 156 | | La fenêtre | Une fenêtre d'édition ordinaire sans nom de fichier : cherchable avec `Ctrl-F`, et `Save as` la conserve | |
| 157 | |
| 158 | ## Rechargement après une commande |
| 159 | |
| 160 | À la fin d'une commande, chaque fichier ouvert est examiné. |
| 161 | |
| 162 | | Le fichier | Ce qui se passe | |
| 163 | | --- | --- | |
| 164 | | Non modifié, et changé sur le disque | Relu ; son langage est redécidé et son titre rafraîchi | |
| 165 | | Non modifié, et inchangé sur le disque | Laissé tel quel, non compté | |
| 166 | | A des modifications non enregistrées | Laissé tel quel et compté comme ignoré | |
| 167 | | N'a jamais reçu de nom | Laissé tel quel | |
| 168 | | A disparu du disque | Laissé tel quel | |
| 169 | |
| 170 | Le curseur reste où il était, borné à ce que le fichier contient désormais. L'historique d'annulation est jeté, parce qu'annuler au-delà d'un rechargement restaurerait un texte que le fichier n'a plus. |
| 171 | |
| 172 | L'arbre du projet est rafraîchi au même moment. |
| 173 | |
| 174 | | Barre d'état | Quand | |
| 175 | | --- | --- | |
| 176 | | `Running <commande>` | La fenêtre s'ouvre | |
| 177 | | `Reloaded 2 files` | Deux fichiers relus, aucun ignoré | |
| 178 | | `Reloaded 2 files; 1 file with unsaved changes left alone` | Certains ont été ignorés | |
| 179 | | `Command finished; 1 file with unsaved changes left alone` | Rien relu, quelque chose ignoré | |
| 180 | |
| 181 | ## Erreurs |
| 182 | |
| 183 | | Message | Cause | |
| 184 | | --- | --- | |
| 185 | | `Cannot read tools` dans le menu | Le fichier est présent mais n'est pas du TOML valide, ou contient un outil sans nom ou sans commande | |
| 186 | | `Already there: .turbo-go/tools.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. | |
| 187 | | `This project has no .turbo-go/tools.toml yet.` | Ouvrir dans un projet qui n'en a pas, de même | |
| 188 | | `Cannot tell which directory this is: …` | Le répertoire de travail n'a pas pu être lu | |
| 189 | | `Terminal windows are not supported on this platform yet` | Lancer une commande dans un terminal exige un pseudo-terminal, que Linux, macOS et Windows possèdent ; voir [Fenêtres terminal](terminal.md) | |
| 190 | |
| 191 | ## Demander une valeur |
| 192 | |
| 193 | Un `{{libellé}}` n'importe où dans une commande est une valeur que l'éditeur demande avant de lancer, dans une boîte portant le nom de l'outil. Le texte entre les accolades est ce que la boîte demande. |
| 194 | |
| 195 | | Écrit | Demandé | Substitué | |
| 196 | | --- | --- | --- | |
| 197 | | `{{chemin du module}}` | `chemin du module` | protégé pour le shell | |
| 198 | | `{{options...}}` | `options` | tel quel | |
| 199 | |
| 200 | Une valeur est **protégée pour le shell** par défaut, si bien qu'un chemin contenant une espace reste un seul argument. Un `...` final à l'intérieur des accolades la demande telle quelle, ce qui permet à un seul champ de valoir plusieurs arguments. |
| 201 | |
| 202 | ```toml |
| 203 | [[tool]] |
| 204 | name = "~I~nit module" |
| 205 | command = "go mod init {{chemin du module}}" |
| 206 | output = "popup" |
| 207 | ``` |
| 208 | |
| 209 | | Règle | Comportement | |
| 210 | | --- | --- | |
| 211 | | Plusieurs libellés | Une boîte, un champ chacun, dans l'ordre où ils apparaissent | |
| 212 | | Le même libellé deux fois | Un seul champ ; chaque occurrence reçoit ce qui y est tapé | |
| 213 | | Un libellé écrit des deux façons | Demandé une fois ; chaque occurrence honore ses propres accolades | |
| 214 | | Échap, ou Annuler | La commande n'est pas lancée | |
| 215 | | Un champ laissé vide | Substitué par du vide — la commande dira elle-même ce qui lui manque | |
| 216 | | Relancer l'outil | La boîte repart de ce qui avait été tapé, pour cette session seulement | |
| 217 | | Plus de champs que l'écran n'en contient | Refusé, avec un message disant combien tiennent | |
| 218 | |
| 219 | **Deux accolades, pas une.** `awk '{print $1}'` et `find . -exec rm {} +` sont des commandes ordinaires, et une syntaxe à une accolade lirait la première comme une demande de valeur nommée `print $1`. |
| 220 | |
| 221 | Rien n'est écrit sur le disque. Une valeur que quelqu'un a tapée cet après-midi n'est pas une décision du projet, elle n'a donc rien à faire dans le répertoire du projet. |
| 222 | |
| 223 | ### Erreurs |
| 224 | |
| 225 | | Erreur | Cause | |
| 226 | | --- | --- | |
| 227 | | `tool "X": "{{module" is never closed` | Une ouverture `{{` sans `}}` après elle | |
| 228 | | `tool "X": {{}} asks for a value but does not say what it is` | Un libellé vide, ou réduit à `...` | |
| 229 | |
| 230 | Les deux sont refusées à la lecture du fichier : un libellé à moitié tapé n'atteint donc jamais le shell avec ses accolades. |
| 231 | |
| 232 | ## Voir aussi |
| 233 | |
| 234 | - [Lancer les commandes go depuis l'éditeur](../how-to/run-go-commands.md) |
| 235 | - [Outils go](../explanation/go-tools.md) |
| 236 | - [Fenêtres terminal](terminal.md) |