turbo-editors/turbo-python · languages.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ v1.0.2

languages.md · 289 lines · 19.7 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# Référence : langages colorés
3> Description neutre des fichiers que Turbo Python colore, de la façon dont il décide, et de ce que reconnaît chaque scanner.
5## Reconnaissance
7L'**extension** d'un fichier décide dès qu'elle fait partie de celles-ci :
Extension | Langage |
--- | --- |
`.py`, `.pyi`, `.pyw` | Python |
`.toml` | TOML |
`.yaml`, `.yml` | YAML |
`.md`, `.markdown` | Markdown |
`.js`, `.mjs`, `.cjs` | JavaScript |
`.html`, `.htm` | HTML |
`.xml`, `.xsd`, `.xsl`, `.xslt`, `.svg`, `.plist`, `.csproj`, `.pom` | XML |
`.sh`, `.bash`, `.zsh` | Shell |
`.dockerfile`, `.containerfile` | Dockerfile |
21Les extensions sont comparées sans tenir compte de la casse, et seule la dernière compte : `main.py.backup` n'est pas du Python.
23Un fichier dont l'extension ne décide de rien est ensuite cherché par son **nom**. Seuls les fichiers sans extension exploitable en ont besoin :
Nom | Langage |
--- | --- |
`Dockerfile`, `Containerfile` | Dockerfile |
29Un nom correspond sur sa totalité ou sur la partie précédant le premier point, sans tenir compte de la casse — ainsi `Dockerfile`, `dockerfile` et `Dockerfile.dev` sont tous reconnus, tandis que `Dockerfile.md` est du Markdown, puisque l'extension est consultée en premier.
31Un fichier qu'aucun des deux tableaux ne revendique est lu par sa **première ligne**. Un shebang nommant `python` ou `python3` en fait du Python ; un shebang nommant un shell — `sh`, `bash`, `zsh`, `dash` ou `ksh` — en fait un script shell. L'interpréteur est reconnu comme élément de chemin ou comme argument d'`env`. C'est ce qui colore un script dans un répertoire `bin`, un hook git, ou `configure`.
Première ligne | Résultat |
--- | --- |
`#!/bin/sh` | Shell |
`#!/usr/bin/env bash` | Shell |
`#!/usr/bin/env -S bash -e` | Shell |
`#!/usr/bin/env python3` | Python |
`#!/usr/bin/python` | Python |
`#!/usr/bin/env node` | Non coloré |
Tout ce qui ne commence pas par `#!` | Non coloré |
43L'ordre est fixe — extension, puis nom, puis première ligne — et le premier qui décide l'emporte : un fichier `.md` commençant par un shebang Python reste du Markdown.
45Tout le reste est affiché en texte brut. Ce n'est pas une erreur — ouvrir un PNG dans l'éditeur n'est pas une faute, c'est simplement non coloré.
47
49Tous les scanners produisent le même vocabulaire de classes, et chacune correspond à une clé de thème.
Classe | Clé de thème | Produite par |
--- | --- | --- |
`identifier` | `syntax.identifier` | Python, TOML, JavaScript, shell, YAML, Dockerfile |
`keyword` | `syntax.keyword` | Python, JavaScript, shell, HTML (doctype), XML, Dockerfile |
`type` | `syntax.type` | Python, TOML (en-têtes de table), YAML (étiquettes) |
`builtin` | `syntax.builtin` | Python, JavaScript, shell (builtins et expansions), YAML (ancres et alias), Dockerfile (variables) |
`constant` | `syntax.constant` | Python, TOML, JavaScript, shell, YAML, HTML et XML (entités) |
`function` | `syntax.function` | Python, JavaScript, shell (la commande) |
`string` | `syntax.string` | tous |
`char` | `syntax.char` | rien ici ; la classe existe pour les langages qui ont un type caractère, et Python n'en a pas |
`number` | `syntax.number` | Python, TOML, JavaScript, shell, YAML, Dockerfile |
`comment` | `syntax.comment` | Python, TOML, JavaScript, shell, HTML, YAML, XML, Dockerfile |
`operator` | `syntax.operator` | Python, TOML, JavaScript, shell, HTML, YAML (en-têtes de scalaire de bloc), XML, Dockerfile |
`punctuation` | `syntax.punctuation` | Python, TOML, JavaScript, shell, Markdown, YAML, Dockerfile |
`heading` | `syntax.heading` | Markdown |
`tag` | `syntax.tag` | HTML, XML |
`attribute` | `syntax.attribute` | Python (décorateurs), HTML, XML, Dockerfile (options) |
`emphasis` | `syntax.emphasis` | Markdown |
`link` | `syntax.link` | Markdown |
71
73Écrit à la main, dans `internal/pythonlang`. **Seule une chaîne franchit un saut de ligne**, et de deux manières : une chaîne à triple guillemet court jusqu'aux trois guillemets correspondants, et une chaîne à guillemet simple ne continue que si la ligne se termine par une contre-oblique. Le guillemet qui l'a ouverte est reporté, car un littéral ouvert par trois guillemets doubles et un littéral ouvert par trois apostrophes sont deux chaînes différentes.
Reconnu | Comme |
--- | --- |
`and`, `as`, `assert`, `async`, `await`, `break`, `class`, `continue`, `def`, `del`, `elif`, `else`, `except`, `finally`, `for`, `from`, `global`, `if`, `import`, `in`, `is`, `lambda`, `nonlocal`, `not`, `or`, `pass`, `raise`, `return`, `try`, `while`, `with`, `yield` | mot-clé |
`match` et `case`, lorsqu'ils ouvrent la ligne et que celle-ci se termine par `:` | mot-clé |
`True`, `False`, `None`, `NotImplemented`, `Ellipsis`, `__debug__` | constante |
`bool`, `bytearray`, `bytes`, `complex`, `dict`, `float`, `frozenset`, `int`, `list`, `memoryview`, `object`, `range`, `set`, `slice`, `str`, `tuple`, `type` | type |
tout autre nom commençant par une majuscule — `ValueError`, `Measurement` | type |
un nom écrit entièrement en majuscules — `MAX_SIZE`, `PI`, `HTTP_PORT` | constante |
`__init__`, `__repr__`, `__name__` et tous les autres noms en double soulignement | primitive |
`print`, `len`, `open`, `sorted`, `isinstance`, … ainsi que `self` et `cls` | primitive |
tout autre nom immédiatement suivi de `(` | fonction |
`"…"` et `'…'`, avec n'importe quel préfixe : `r`, `b`, `u`, `f`, `rb`, `br`, `fr`, `rf`, dans les deux casses | chaîne |
`"""…"""` et `'''…'''`, sur autant de lignes qu'il faut | chaîne |
une chaîne à guillemet simple dont la ligne finit par une contre-oblique, sur la ligne suivante | chaîne |
`42`, `1_000`, `0xFF`, `0o17`, `0b1010`, `.5`, `1.`, `1.5e-3`, `1E+7`, `3j` | nombre |
`#` jusqu'à la fin de la ligne, shebang compris | commentaire |
`@property`, `@app.route`, `@pytest.mark.parametrize` — le nom seulement | attribut |
`:=` | opérateur |
`:` partout ailleurs — un bloc, une tranche, un dictionnaire, une annotation | ponctuation |
`@` ailleurs qu'en début de ligne | opérateur |
une `\` en fin de ligne | ponctuation |
suites de `+-*/%=<>!&\|^~?` | opérateur |
`()[]{},;.` | ponctuation |
99**`match` et `case` ne sont des mots-clés que là où une instruction `match` les place.** Ils ne sont réservés dans aucun contexte — `match = re.match(motif, texte)` est du Python ordinaire — c'est donc la forme de l'instruction qui décide : le mot ouvre la ligne, et la ligne se termine par le deux-points qui ouvre son bloc. Les deux conditions doivent tenir.
101**Un nom écrit entièrement en majuscules est une constante, et tout autre nom capitalisé est un type.** La PEP 8 sépare assez nettement les deux conventions pour qu'on puisse les lire : `MAX_SIZE` est une constante et `Measurement` une classe. Turbo Rust n'a que la seconde règle et documente `SCREAMING_SNAKE_CASE` comme une réponse fausse connue ; ici, cette réponse mérite d'être supprimée plutôt qu'héritée.
103**Un nom capitalisé est un type même lorsqu'il est appelé.** `ValueError("non")` et `parse("non")` ont exactement la même forme, parce qu'une classe s'appelle comme une fonction — la parenthèse ne peut donc pas les distinguer, et c'est la convention qui doit le faire. C'est la seule règle que Turbo Python et Turbo Rust ordonnent différemment.
105**`self` et `cls` sont colorés comme des primitives bien que le langage ne les nomme pas.** C'est une convention : une méthode peut appeler son premier paramètre comme elle veut. Mais tout lecteur de Python lit `self` comme appartenant au langage, de la même façon qu'un lecteur de Rust lit `Some`, et tous les autres coloriseurs font pareil. Le prix à payer : un paramètre honnêtement nommé `self` dans une fonction ordinaire est coloré lui aussi.
107**Un décorateur s'arrête à ses arguments.** `@pytest.mark.parametrize("n", [1, 2])` colore le nom pointé comme un attribut et le reste comme du Python ordinaire, si bien que la chaîne et la liste qu'il contient gardent leurs propres couleurs.
109**Une contre-oblique soustrait le caractère qui la suit, y compris dans une chaîne brute.** `r"\""` est une chaîne complète : dans une chaîne brute la contre-oblique reste dans la valeur, mais elle empêche toujours le guillemet suivant de terminer le littéral. La règle de terminaison est donc la même pour les deux, et c'est pourquoi le caractère « brut » n'est pas reporté d'une ligne à l'autre.
111**Une chaîne qui atteint la fin d'une ligne sans l'une des deux raisons de continuer s'arrête là.** Elle est colorée jusqu'au bout de cette ligne et la ligne suivante redevient du code — parce qu'une chaîne à guillemet simple sans guillemet fermant est du code en cours de frappe, et que la reporter peindrait tout le reste du fichier.
113**Non reconnu**, chaque fois pour une raison énoncée :
Non reconnu | Parce que |
--- | --- |
L'`{expression}` à l'intérieur d'une f-string | Depuis Python 3.12 elle peut contenir n'importe quoi — guillemets imbriqués, commentaires, une autre f-string. Une seule plage de chaîne est la réponse honnête ; la colorer à moitié terminerait `f"{n:{width}}"` sur l'accolade intérieure |
`match` ou `case` sur une ligne portant un commentaire de fin | Le deux-points est cherché en remontant depuis la fin de la ligne, et un commentaire le masque : `match value:  # aiguillage` colore donc `match` comme un nom. C'est le bon sens de l'erreur |
Une docstring comme autre chose qu'une chaîne | C'en *est* une — `help()` la relit comme telle — et la colorer en commentaire serait faux dès qu'on en affecte une à un nom |
Une classe dont le nom est tout en majuscules | `HTTP` est coloré comme une constante. C'est le prix de `MAX_SIZE` correctement coloré, et l'arbitrage suit le cas le plus fréquent |
`type` comme mot-clé souple de `type Alias = int` | C'est aussi un type primitif, et le lire comme le type est juste dans ses deux emplois |
Si un nom est lié dans cette portée | Rien ici ne lit plus d'une ligne à la fois ; c'est la question du serveur de langage, et [F1 y répond](../how-to/ask-about-code.md) |
Reconnu | Comme |
--- | --- |
`# commentaire` | comment |
`[table]`, `[[array]]` | le nom en type, les crochets en punctuation |
`clé =` | identifier, puis operator |
`"basique"`, `'littérale'`, `"""multi-ligne"""`, `'''multi-ligne'''` | string |
`true`, `false` | constant |
nombres, dates, heures, `inf`, `nan` | number |
137Un fichier compose, un manifeste Kubernetes et un workflow d'intégration continue sont tous cela : il n'y a pas de dialecte séparé, parce qu'un dialecte serait le schéma de quelqu'un d'autre à maintenir en phase.
Reconnu | Comme |
--- | --- |
`# commentaire` | commentaire |
`clé:` suivie d'une espace ou de la fin de ligne | la clé en identifiant, le deux-points en ponctuation |
`"entre guillemets": 1`, `'apostrophes': 1` | la clé citée en identifiant |
`- ` ouvrant une entrée de séquence | ponctuation |
`"…"`, `'…'` | chaîne |
`true`, `false`, `yes`, `no`, `on`, `off`, `null` | constante, quelle que soit la casse |
nombres, dates et heures écrits sans guillemets | nombre |
`&ancre`, `*alias` | builtin |
`!!str`, `!Custom` | type |
`---`, `...` | toute la ligne en ponctuation |
`{`, `}`, `[`, `]`, `,` | ponctuation |
`\|`, `>`, avec leurs indicateurs de coupe et d'indentation | l'en-tête en opérateur, le corps en chaîne |
154**Un deux-points n'est un séparateur que si une espace ou la fin de ligne le suit.** `image: nginx:1.27` est une clé et une seule valeur, et `url: http://example.com/x` une clé et une seule URL — colorer les deux-points intérieurs en séparateurs mettrait chaque étiquette d'image et chaque URL en trois couleurs.
156**L'étendue d'un scalaire de bloc est décidée par l'indentation**, pas par un délimiteur. La première ligne de contenu après `|` ou `>` fixe l'indentation du bloc ; toute ligne indentée au moins autant lui appartient, et la première qui ne l'est pas y met fin. **Une ligne vide à l'intérieur d'un bloc y reste** : un scalaire littéral conserve ses lignes vides, et terminer le bloc au premier saut de paragraphe couperait en deux un script shell dans un fichier d'intégration continue.
158**Un `#` a besoin d'une espace devant lui pour ouvrir un commentaire**, si bien que `colour: ff#00aa` est un seul scalaire.
Non reconnu | Parce que |
--- | --- |
Le schéma d'un fichier compose, d'un manifeste ou d'un workflow | Colorer `services:` autrement qu'une clé quelconque revient à transporter le schéma de quelqu'un d'autre, qui se périme le jour où il ajoute une clé |
Les flux multi-documents comme documents distincts | `---` est coloré, mais rien n'est réinitialisé à cet endroit ; rien dans la coloration ne dépend des frontières de documents |
Si un mot nu est une chaîne ou un nombre pour un analyseur | `1.2.3` est une version pour un lecteur et une chaîne pour YAML ; l'analyseur colore ce à quoi cela ressemble |
166## Markdown
Reconnu | Comme |
--- | --- |
`# Titre` … `###### Titre` | toute la ligne en heading |
`**gras**`, `__gras__`, `*italique*`, `_italique_` | emphasis |
`` `code` `` | string |
`[texte](cible)`, `![alt](src)` | l'ensemble en link |
`- `, `* `, `+ `, `1. `, `1) ` | le marqueur en punctuation |
`>` | punctuation |
`---`, `***`, `___` | punctuation |
clôtures ` ``` ` et `~~~` | tout le bloc, lignes d'ouverture et de fermeture comprises, en string |
179Un bloc clôturé est **d'une seule couleur quel que soit le langage annoncé** : ```` ```python ```` ne colore pas son contenu en Python. La suite de marqueurs qui ouvre un bloc doit être fermée par le même caractère : une clôture en accents graves ne se ferme pas par des tildes. Une clôture non fermée colore jusqu'à la fin du fichier.
181La suite de marqueurs qui ouvre une emphase doit être fermée par une suite de même longueur, de sorte que `**gras**` fasse un seul span et non deux italiques.
183## JavaScript
Reconnu | Comme |
--- | --- |
`const`, `let`, `function`, `class`, `async`, `await`, `import`, `export`, … | keyword |
`true`, `false`, `null`, `undefined`, `NaN`, `Infinity`, `this` | constant |
`console`, `document`, `window`, `Array`, `Object`, `Promise`, `Math`, `JSON`, … | builtin |
un nom immédiatement suivi de `(` | function |
`"…"`, `'…'` | string |
`` `…` ``, interpolations comprises, sur plusieurs lignes | string |
`//` jusqu'à la fin de la ligne, `/* … */` sur plusieurs lignes | comment |
`42`, `3.14`, `0x1f`, `0b1010`, `0o777`, `1_000_000`, `1e6`, `10n` | number |
suites de `+-*/%=<>!&|^~?:` | operator |
`()[]{},;.` | punctuation |
198**Les littéraux d'expression régulière ne sont pas reconnus.** Distinguer `/x/g` d'une division exige de savoir si le token précédent pouvait terminer une expression ; une mauvaise supposition colore le reste de la ligne comme une chaîne, ce qui est pire que de laisser une regex à la couleur d'un opérateur.
200Les globales sont reconnues par leur nom : un fichier qui masque `Math` la voit quand même colorée comme un builtin — la même règle que les types primitifs de Python.
Reconnu | Comme |
--- | --- |
`<balise`, `</balise`, `>`, `/>` | tag |
noms d'attributs, dont `data-*`, `xlink:href`, `@click`, `v-bind.prop` | attribute |
`=` | operator |
`"…"`, `'…'` | string |
`<!-- … -->`, sur plusieurs lignes | comment |
`&amp;`, `&#169;` | constant |
`<!DOCTYPE …>` et les autres déclarations | keyword |
214Le texte entre balises n'est pas coloré. Une esperluette isolée sans `;` dans les 32 caractères qui suivent est laissée telle quelle, parce que c'est du texte légal.
216**Le contenu de `<script>` et de `<style>` n'est pas coloré** en JavaScript ni en CSS.
220Son propre analyseur plutôt que celui du HTML, pour une raison qui compte : CDATA. Tout l'intérêt de `<![CDATA[ … ]]>` est que son contenu n'est *pas* du balisage, et colorer les balises qu'il contient comme des balises est exactement l'inverse.
Reconnu | Comme |
--- | --- |
`<?xml version="1.0"?>` et les autres instructions de traitement | la cible et `?>` en mot-clé, les paires entre les deux en attributs et chaînes |
`<!DOCTYPE …>` et les autres formes `<!` | mot-clé |
`<!-- … -->`, sur plusieurs lignes | commentaire |
`<![CDATA[ … ]]>`, sur plusieurs lignes | chaîne |
`<balise`, `</balise`, `>`, `/>` | balise |
`<ns:balise>`, `xsi:type` | le préfixe et le nom local en **un seul** segment |
les noms d'attributs | attribut |
`=` | opérateur |
`"…"`, `'…'` | chaîne |
`&amp;`, `&#169;` | constante |
235**Un commentaire et une section CDATA se ferment sur des délimiteurs différents**, et sont transportés séparément : un `-->` à l'intérieur d'une section CDATA n'y met pas fin.
237**Une esperluette isolée sans point-virgule dans les 32 caractères suivants est laissée telle quelle**, parce que c'est du texte légal dans bien des documents et qu'avaler le reste de la ligne serait la plus grosse erreur.
239Le texte entre balises n'est pas coloré.
241
243S'applique indifféremment à `sh`, `bash` et `zsh` : les mots-clés reconnus sont ceux qu'ils partagent.
Reconnu | Comme |
--- | --- |
`if`, `then`, `fi`, `for`, `while`, `case`, `esac`, `function`, `return`, … | keyword |
`true`, `false` | constant |
`echo`, `printf`, `export`, `local`, `read`, `cd`, `set`, `source`, … | builtin |
`$NOM`, `${…}`, `$(…)`, `$1`, `$?`, `$@` | builtin |
le **premier mot nu d'une ligne** | function |
tout mot nu suivant, et `NOM` dans `NOM=valeur` | identifier |
`'…'`, sans échappement ni expansion à l'intérieur | string |
`"…"`, avec les expansions colorées comme telles | string |
`#` jusqu'à la fin de la ligne | comment |
257`$(a $(b) c)` fait un seul span : l'imbrication est comptée. Une option comme `-euo` est un seul mot, et non un moins suivi d'un mot.
259**Les heredocs ne sont pas reconnus.** `<<EOF` et le texte qui suit sont colorés comme du shell ordinaire.
261## Dockerfile
Reconnu | Comme |
--- | --- |
`FROM`, `RUN`, `COPY`, `ADD`, `ARG`, `ENV`, `CMD`, `ENTRYPOINT`, `EXPOSE`, `LABEL`, `USER`, `VOLUME`, `WORKDIR`, `HEALTHCHECK`, `ONBUILD`, `SHELL`, `STOPSIGNAL`, `MAINTAINER` | mot-clé, quelle que soit la casse |
`AS`, `NONE` | mot-clé |
`# commentaire`, y compris les directives `# syntax=` et `# escape=` | commentaire |
`--from=builder`, `--chown=me:me` | le nom de l'option en attribut |
`$NOM`, `${NOM}`, `${NOM:-defaut}` | builtin, en un seul segment jusqu'à l'accolade fermante |
`"…"`, `'…'` | chaîne |
un `\` final | opérateur |
les nombres | nombre |
chemins et références d'images — `/usr/local/bin`, `golang:1.26-alpine` | identifiant, en **un seul** segment |
275**Seul le premier mot d'une ligne peut être une instruction**, et un mot qui n'en est pas une est un argument — ce qui garde le premier mot d'une ligne de continuation hors de la couleur des mots-clés.
277**Rien ne traverse un saut de ligne.** Un `\` joint deux lignes pour Docker, mais chaque moitié se lit encore comme une commande et est colorée pour elle-même.
Non reconnu | Parce que |
--- | --- |
Le shell à l'intérieur d'un `RUN` | Il faudrait passer l'analyseur shell sur une partie de ligne et en remonter les colonnes, et un `RUN` peut contenir n'importe quel langage |
Les heredocs dans un `RUN` | La même raison que pour l'analyseur shell |
Quelle étape nomme un `--from` | Rien ici ne lit le reste du fichier |
285## Voir aussi
287- [Format des fichiers de thème](themes.md) — toutes les clés vers lesquelles ces classes se résolvent
288- [Coloration et complétion](../explanation/colouring-and-completion.md) — pourquoi les scanners sont écrits ainsi
289- [Écrire son propre thème](../how-to/write-a-theme.md)