Référence : snippets

  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
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# Référence : snippets

> Description neutre des fichiers de snippets, du menu Snippets, et de la façon dont un snippet est inséré.

## Fichiers

Les deux sont lus, et les deux sont facultatifs.

| Fichier | Contient |
| --- | --- |
| `./.turbo-python/snippets.toml` | Les snippets du projet |
| `$TURBO_PYTHON_SNIPPET_DIR/snippets.toml`, sinon `<config utilisateur>/turbo-python/snippets.toml` | Les vôtres, partagés entre projets |

`<config utilisateur>` est `os.UserConfigDir()` : `~/.config` sous Linux, `~/Library/Application Support` sous macOS.

| Propriété | Valeur |
| --- | --- |
| Recherche du projet | Le répertoire de travail seulement. Les dossiers parents ne sont **pas** parcourus. |
| Lecture | À chaque ouverture du menu Snippets |
| Ordre | Les vôtres d'abord, puis ceux du projet |
| Conflit de nom | Même `group` **et** même `name` → celui du projet remplace le vôtre |
| Fichier absent | Pas une erreur |
| Fichier illisible | Une erreur, signalée dans le menu |

## Format du fichier

Une table `[[snippet]]` par snippet.

| Clé | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `name` | chaîne | oui | Ce que le menu affiche |
| `body` | chaîne | oui | Le texte inséré au curseur |
| `group` | chaîne | non | Le sous-menu où il va ; absent signifie `General` |
| `languages` | tableau de chaînes | non | Restreint le snippet à ces langages ; absent signifie tous les fichiers |

`languages` emploie les noms de langages de l'éditeur : `python`, `toml`, `yaml`, `markdown`, `javascript`, `html`, `xml`, `dockerfile`, `bash`. Voir [Langages colorés](languages.md).

Un snippet sans `name` ou sans `body` rend tout le fichier erroné — il n'aurait pu être affiché, ou n'aurait rien à insérer.

### Exemple

```toml
[[snippet]]
name = "if err != nil"
group = "Python"
languages = ["python"]
body = """
if err != nil {
	return err
}"""
```

Les chaînes `"""` du TOML suppriment le saut de ligne qui suit immédiatement les guillemets d'ouverture, et interprètent `\t` comme une tabulation.

## Le menu

| Entrée | Condition |
| --- | --- |
| 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 |
| `Cannot read snippets`, grisé | Un fichier est présent mais illisible |
| `Create snippets file` | Le projet n'a pas de fichier d'extraits |
| `Open snippets file` | Le projet en a un |

La touche d'accès du menu est `Alt-N`, pas `Alt-S` : Search répond déjà au S.

Les groupes, et les snippets à l'intérieur, sortent dans l'ordre de lecture : le menu correspond aux fichiers.

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.

### Filtrage

| Fenêtre au premier plan | Snippets proposés |
| --- | --- |
| Un fichier d'un langage reconnu | Ceux qui nomment ce langage, plus ceux qui n'en nomment aucun |
| Un fichier d'aucun langage reconnu | Ceux qui n'en nomment aucun |
| Un terminal, l'arbre du projet, ou rien | Ceux qui n'en nomment aucun |

## Insertion

| Comportement | Détail |
| --- | --- |
| Position | Au curseur |
| Première ligne | Insérée là où est le curseur |
| Lignes suivantes | Préfixées par l'indentation de la ligne où était le curseur |
| Lignes vides du corps | Laissées vides, non complétées d'espaces |
| Annulation | Une seule opération pour tout le snippet |
| Curseur ensuite | À la fin du texte inséré |
| Signalement | `Snippet inserted` dans la barre d'état |

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à.

## Entrées de menu

| Entrée | Menu | Effet |
| --- | --- | --- |
| Create snippets file | Snippets | Écrit `.turbo-python/snippets.toml` avec des exemples travaillés, puis l'ouvre. Grisée dès que le projet en a un. |
| Open snippets file | Snippets | Ouvre `.turbo-python/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. |

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.

## Erreurs

| Message | Cause |
| --- | --- |
| `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 |
| `Already there: .turbo-python/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. |
| `This project has no .turbo-python/snippets.toml yet.` | Ouvrir dans un projet qui n'en a pas, de même |
| `Cannot tell which directory this is: …` | Le répertoire de travail n'a pas pu être lu |

## Voir aussi

- [Insérer des snippets depuis un menu](../how-to/use-snippets.md)
- [Snippets](../explanation/snippets.md)
- [Clavier](keyboard.md)