Comment écrire les fichiers de départ

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# Comment écrire les fichiers de départ

Ce guide montre comment écrire les trois modèles que votre éditeur propose de créer dans un projet. Il suppose que vous avez un éditeur et un `profile.Templates` à remplir.

Tout éditeur bâti sur turbo-core propose trois entrées de menu qui écrivent un fichier dans le répertoire propre au projet : **Options ▸ Create project settings**, **Snippets ▸ Create snippets file**, et **Create tools file** au bas du menu de la chaîne d'outils. Chacune a une partenaire qui ouvre le fichier au lieu de l'écrire, et exactement une des deux est disponible à la fois : on peut créer le fichier que le projet n'a pas, et ouvrir celui qu'il a. Ce que disent ces fichiers vous appartient ; le fait qu'ils soient écrits sans risque appartient à la bibliothèque.

## Étapes

### 1. Les écrire comme du texte, pas comme des structures

Ils sont faits pour être lus et modifiés par une personne. Les commentaires qu'ils contiennent disent à quoi sert chaque clé, ce qui est toute la raison pour laquelle l'éditeur propose d'en créer un plutôt que seulement d'en lire un. Les encoder depuis une structure serait plus court et produirait un fichier sans aucun commentaire.

### 2. Remplir les trous que la bibliothèque fournit

Chaque modèle prend un ensemble fixe d'arguments, dans un ordre fixe :

| Modèle | Verbe | Ordre |
| --- | --- | --- |
| `Settings` | `%q`, `%q` | le nom du thème, puis le délai de sauvegarde automatique |
| `Snippets` | `%s`, `%s` | le nom du groupe sans nom, puis le chemin des extraits de l'utilisateur |
| `Tools` | — | aucun |

Se tromper là-dessus se voit sous la forme de `%!s(MISSING)` dans le projet de quelqu'un, donc cela mérite un test :

```go
func TestTheSnippetsTemplateTakesExactlyTwoBlanks(t *testing.T) {
	if got := strings.Count(snippetsTemplate, "%s"); got != 2 {
		t.Errorf("le modèle d'extraits a %d %%s, on en veut 2", got)
	}
}
```

### 3. Nommer votre éditeur, pas celui que vous avez copié

L'erreur la plus probable dans un deuxième éditeur est un `turbo-go` oublié dans un fichier écrit à l'intérieur du projet Rust de quelqu'un. Elle est invisible pour tous les autres tests, donc testez-la directement :

```go
if strings.Contains(template, "turbo-go") {
	t.Errorf("le modèle %s dit encore turbo-go", name)
}
```

### 4. Tester ici ce qu'ils contiennent

Que `Create` écrive le modèle du profil, c'est le test de turbo-core. Ce que le modèle *dit* — que Build lance `cargo build`, que Run est le seul outil dans un terminal, que chaque outil nomme sa sortie — c'est le test de votre éditeur, parce que cela parle de votre langage.

## Les garder dans des fichiers, pas dans des constantes

`profile.Templates` prend trois chaînes, et une constante Go est la façon évidente d'en fournir une. Chaque éditeur les garde plutôt dans des fichiers à côté du code, embarqués à la compilation :

```go
//go:embed settings.toml.tmpl
var settingsTemplate string
```

Deux raisons. Un fichier de départ est de la prose qui a une forme — commentaires, lignes vides, alignements — et cela se lit et s'édite bien mieux comme fichier que dans un littéral brut qui ne peut pas contenir de backtick. Et un fichier s'ouvre dans l'éditeur qu'on est en train de construire, dans le langage dont il est le gabarit.

**Le suffixe `.tmpl` n'est pas décoratif.** Chaque fichier passe par `fmt.Sprintf` avant d'être écrit, et le gabarit de réglages contient `theme = %q`, qui n'est pas du TOML valide. L'appeler `settings.toml` serait une promesse intenable : un linter TOML le rejetterait, et l'éditeur le colorerait comme du TOML en le montrant cassé.

Les sortir du source coûte une garde, et elle vaut la peine d'être écrite : les verbes ne sont plus à côté du contrat qui les documente, donc plus rien ne remarque qu'on en ajoute ou qu'on en retire un. Comptez-les, et remplissez chaque gabarit pour vérifier qu'aucun marqueur `%!` n'en sort — Go écrit `%!q(MISSING)` dans la sortie au lieu d'échouer, donc un mauvais compte produit un fichier écrit, ouvert, et faux.

## Variantes

### Votre langage s'indente avec des tabulations

Écrivez `\t` sous forme des deux caractères barre-oblique-inverse et t à l'intérieur de la chaîne TOML. TOML transforme l'échappement en tabulation à la lecture, alors qu'une vraie tabulation dans le modèle ressemblerait à ce que l'éditeur du lecteur fait des tabulations. Puis testez que la tabulation a survécu :

```go
if !strings.Contains(snippet.Body, "\treturn err") {
	t.Errorf("le corps est %q ; la tabulation n'a pas survécu", snippet.Body)
}
```

### Votre langage s'indente avec des espaces

Rien à échapper. Testez plutôt qu'aucune tabulation ne s'est glissée dedans — une tabulation dans un extrait Rust atterrit dans le fichier de quelqu'un et disparaît au prochain `cargo fmt`, ce qui fait une différence que personne n'a demandée.

### L'utilisateur n'a pas de répertoire de configuration

`snippets.UserPath` renvoie `""`, et le commentaire du modèle dirait « Vos propres extraits vont dans : » suivi de rien. La bibliothèque remplit « (no configuration directory on this system) » à votre place ; prévoyez la place d'une phrase plutôt que d'un chemin.

## Voir aussi

- Les modèles champ par champ : [référence profile](../reference/profile.md)
- Pourquoi les fichiers ne sont créés que sur demande : [ce qui appartient ici](../explanation/what-belongs-here.md)