Documentation · cibles
Ce que Sapphire 3 traduit, cible par cible
Le même modèle logique alimente trois backends : JavaScript, Python et un C expérimental. Cette page dit exactement ce que chacun accepte, comment les fonctions et opérations SP3 sont reliées à leurs équivalents, et ce qui est refusé avant toute émission de code.
Documents liés
- Le modèle AST — simulation, débogage et transpilation pour les contrats du moteur.
- L’état du projet pour les limites générales et les plateformes.
- Dans le dépôt :
docs/TRANSPILATION.mdpour la version détaillée etdocs/LOGIC_API.mdpour les contrats du moteur.
1 · Chaîne commune
La transpilation n’est jamais automatique. Le document source, l’AST, les portées, les types et les diagnostics restent indépendants du langage cible. Une action explicite lance la chaîne suivante.
analyzeProgram()construit l’AST, les symboles, les types et les diagnostics.- Les gardes globales refusent les projets contenant une carte widget ou d’entrée, quelle que soit la cible.
createGenerationContext()réserve les noms, résout les imports et les références, prépare les classes et le point d’entrée.- Le backend choisi émet un fichier ou un extrait, avec ses propres helpers.
- Les diagnostics du backend sont fusionnés avec ceux de l’analyse ; une erreur bloquante rend le résultat
ok: false.
Un programme complet exige exactement un point d’entrée sans paramètre. Un aperçu de sélection
(transpileSelection) n’exige pas de point d’entrée et ne produit jamais un fichier autonome.
Les contrats attachés aux variables, constantes et paramètres sont vérifiés par le simulateur et le
Run live ; ils ne sont pas émis dans le code généré.
2 · Matrice de périmètre
« Partiel » signifie que la construction est acceptée, mais que certaines opérations du registre natif n’ont pas encore d’émission. Une construction absente est refusée avec un diagnostic stable, jamais traduite approximativement.
| Construction SP3 | JavaScript | Python | C expérimental |
|---|---|---|---|
| Primitifs numériques et booléen | Oui | Oui | Oui |
string | Oui | Oui | Oui, en const char * UTF-8 |
char | Oui | Oui | Non |
| Fonctions, paramètres, retours | Oui | Oui | Oui |
| Variables et constantes | Oui | Oui | Oui, avec initialiseur obligatoire |
Blocs, if, while, for, break, continue | Oui | Oui | Oui |
Print | Oui | Oui | Oui, sauf pointeur |
| Tableaux | Oui | Oui | Non |
Pointeurs & / * | Oui, par cellules | Oui, par cellules | Oui, pointeurs natifs |
| Références de fonction | Oui | Oui | Oui, fonctions nommées |
| Lambdas et fermetures | Oui | Oui | Lambdas sans capture |
ForEach | Oui | Oui | Non |
Classes, new, this, membres | Oui | Oui | Non |
| Génériques | Oui, fonction ordinaire | Oui, fonction ordinaire | Non |
MathCall | Partiel | Partiel | Non |
| Conversions explicites | Oui | Oui | Non |
| Contrats | Non émis | Non émis | Non émis |
| Cartes widget et entrées | Refusées | Refusées | Refusées |
Les opérations arrayFill, arrayConvolve et arrayLookup ne sont
pas encore transpilées vers JavaScript/Python. Les opérations d’écran sont hors sujet : toute carte
Screen rend le projet non transpilable.
3 · JavaScript
Cible active, fichier .js unique sans import ni export. Les noms
de modules et de fonctions deviennent des identifiants stables, par exemple Library_square.
| Élément SP3 | Émission JavaScript |
|---|---|
Print | console.log(sapphireFormat(valeur)) |
| Nombres | sapphireNumeric, sapphireChecked ; entiers en BigInt interne |
| Tableaux | tableaux JavaScript, sapphireArray, sapphireElement, sapphireWrite |
| Pointeurs | jeton d’adresse, sapphirePointer, sapphireDeref, sapphireDerefWrite |
ForEach | sapphireForEach(copie, callback) |
| Références et lambdas | valeur de fonction, fonction fléchée |
| Classes | class, constructor, champs par instance, méthodes ; sapphireMember lie les méthodes |
Print d’une classe | sapphireFormat produit ClassName { champ: valeur } |
MathCall | Math.*, sapphireInteger*, sapphireArray*, sapphireString* |
Chaînes et char | chaînes JavaScript ; Array.from pour les scalaires Unicode |
| Génériques | une seule fonction ordinaire, sans spécialisation |
Refus principaux
Cartes widget, arrayFill, arrayConvolve, arrayLookup, et les expressions ou instructions qu’un backend ne sait pas encore émettre (TRANSPILE_EXPRESSION_UNSUPPORTED, TRANSPILE_STATEMENT_UNSUPPORTED, TRANSPILE_LITERAL_UNSUPPORTED).
4 · Python
Cible active, fichier .py unique avec un runtime Python embarqué. Les globales affectées
sont déclarées avec global dans les fonctions qui les modifient.
| Élément SP3 | Émission Python |
|---|---|
Print | print(sapphireFormat(valeur)) |
| Nombres | sapphireBinary, sapphireUnary, sapphireCheck |
| Tableaux | listes Python, sapphireArray, sapphireElement, sapphireWrite |
| Pointeurs | cellule à un élément et _SapphirePointer |
ForEach | sapphireForEach(liste, callback) avec copie |
| Références et lambdas | callable Python, lambda |
| Classes | class, __init__, méthodes, self ; sapphireMember |
Print d’une classe | sapphireFormat produit ClassName { champ: valeur } |
MathCall | math.*, sapphireClamp, sapphireSign, sapphireArray*, sapphireString* |
| Conversions | sapphireCast |
Chaînes et char | str Python, indexation par scalaires Unicode |
| Génériques | une seule fonction ordinaire, sans spécialisation |
Refus principaux
Cartes widget, arrayFill, arrayConvolve, arrayLookup, et les textes Unicode contenant un surrogate isolé (TRANSPILE_PYTHON_STRING_UNSUPPORTED).
5 · C expérimental
Cible active mais volontairement restreinte : fichier .c C11 unique. Les helpers
flottants utilisent <math.h> ; compiler avec cc -std=c11 … -lm sur
les plateformes qui séparent la bibliothèque mathématique.
| Élément SP3 | Émission C |
|---|---|
| Types | int16_t, uint16_t, int32_t, uint32_t, float, double, const char *, bool |
| Fonctions | Module_fonction, prototypes avant les définitions |
Print | sapphire_print_* pour chaque type primitif |
| Entiers | sapphire_i* et sapphire_u* : bornes et division par zéro |
| Flottants | sapphire_f32_* et sapphire_f64_* : infinis, sous-flux et division par zéro |
| Flottants imprimés | représentation décimale courte qui round-trip, notation fixe entre 1e-6 et 1e21 |
| Pointeurs | &variable, ¶mètre, *p ; adresse d’une constante refusée |
| Références de fonction | pointeurs de fonction typés (typedef), paramètres, variables et retours |
| Lambdas | fonction statique générée, utilisée comme pointeur de fonction ; capture refusée |
| Chaînes | const char * UTF-8, égalité par strcmp ; NUL et surrogates isolés refusés |
| Globales | static T nom;, initialisées dans main() dans l’ordre topologique |
| Point d’entrée | Module_<entrée>() appelé depuis le main C |
Refus explicites avec TRANSPILE_C_UNSUPPORTED : tableaux, classes, lambdas
capturantes et fermetures, ForEach, MathCall, conversions explicites,
char, variables sans initialiseur et adresse d’une constante. Les pointeurs de fonction
nommés et les lambdas sans capture sont acceptés ; Print d’un pointeur de fonction
reste refusé. Le backend vérifie ces limites avant d’émettre le fichier.
Limites connues du C
- Les globales non encore initialisées valent zéro avant leur affectation.
- Un pointeur vers une variable locale ne doit pas survivre à sa fonction.
- Les flottants de magnitude extrême peuvent différer du format JavaScript.
- C++ et Java restent indisponibles.
6 · Fonctions et opérations
Un module n’est pas émis comme un objet d’exécution : ses fonctions deviennent des fonctions du
langage cible, préfixées par le nom du module. Un import ne produit ni import JavaScript,
ni import Python, ni inclusion C : la référence importée est résolue vers le nom généré
de la fonction exportée. Le fichier reste autonome.
Une fonction ordinaire est émise une seule fois, avec ses paramètres concrets. Les génériques ne créent pas de copie : JavaScript/Python émettent la même fonction ordinaire et la simulation applique les types inférés. C refuse les types génériques. Les références de fonction sont des valeurs de première classe en JavaScript et Python ; C accepte les fonctions nommées via des pointeurs typés et lève les lambdas sans capture en fonctions statiques. Une lambda qui capture une variable locale ou un paramètre reste refusée, faute d’environnement de fermeture.
Le registre src/utils/logic/mathNatives.js est le catalogue unique des opérations natives
SP3 : identifiant stable, catégorie, signature et groupe d’interface. Les backends ne recréent pas
ce catalogue ; ils fournissent chacun une table de correspondance par identifiant :
nativeJavaScript, nativePython, et le backend C refuse actuellement toutes les
MathCall. Une opération présente dans le registre mais absente de la table du backend produit
un diagnostic stable (TRANSPILE_EXPRESSION_UNSUPPORTED en JavaScript/Python,
TRANSPILE_C_UNSUPPORTED en C).
Ajouter une opération
- L’ajouter au registre
mathNatives.jsavec sa signature et son groupe. - Ajouter son émission dans
nativeJavaScriptet/ounativePython. - Si la cible C doit la porter, ajouter un helper et une émission C ; sinon la laisser refusée.
- Ajouter un test qui compare la simulation et le code généré.
7 · Refus et limites
Les refus sont des diagnostics stables, pas des traductions approximatives. Le projet reste inspectable et modifiable ; seule la génération est bloquée.
| Code | Signification |
|---|---|
TRANSPILE_TARGET_UNSUPPORTED | Cible inconnue ou non installée |
TRANSPILE_ENTRY_POINT_REQUIRED, TRANSPILE_ENTRY_POINT_INPUTS, TRANSPILE_ENTRY_POINT_DUPLICATE | Point d’entrée absent, paramétré ou multiple |
TRANSPILE_REFERENCE_UNRESOLVED | Référence non résolue |
TRANSPILE_SCREEN_UNSUPPORTED, TRANSPILE_GAUGE_UNSUPPORTED, TRANSPILE_PROGRESS_UNSUPPORTED, TRANSPILE_BAR_CHART_UNSUPPORTED, TRANSPILE_XY_PLOT_UNSUPPORTED, TRANSPILE_OSCILLOSCOPE_UNSUPPORTED, TRANSPILE_HEATMAP_UNSUPPORTED, TRANSPILE_LED_UNSUPPORTED, TRANSPILE_RGB_LED_UNSUPPORTED | Carte graphique non transpilable |
TRANSPILE_INPUT_BUTTON_UNSUPPORTED, TRANSPILE_INPUT_NUMBER_UNSUPPORTED, TRANSPILE_INPUT_STRING_UNSUPPORTED, TRANSPILE_RGB_PICKER_UNSUPPORTED, TRANSPILE_RGBA_PICKER_UNSUPPORTED | Entrée ou sélecteur non transpilable |
TRANSPILE_C_UNSUPPORTED | Construction hors du sous-ensemble C expérimental |
TRANSPILE_EXPRESSION_UNSUPPORTED, TRANSPILE_STATEMENT_UNSUPPORTED, TRANSPILE_LITERAL_UNSUPPORTED | Trou de couverture d’un backend JavaScript/Python |
La suite de tests compile et exécute les fichiers C générés avec cc -std=c11. Les exemples
Fibonacci, Recursion, Imports, Pointers, Higher-order et Calculus produisent la même sortie que le
simulateur en C. Les tests couvrent aussi les lambdas sans capture et le refus des lambdas capturantes.
JavaScript et Python couvrent en plus les tableaux, les lambdas, ForEach, les classes et les
opérations natives prises en charge.