Sasedev/saselang-bible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.12

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-12 08:56:27 +02:00
parent 426aa92d0d
commit 18306bdc8c
116 changed files with 11080 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.settings/org.eclipse.core.resources.prefs Normal file
View File

@@ -0,0 +1,2 @@
eclipse.preferences.version=1
encoding/<project>=UTF-8

24
000-README.md Normal file
View File

@@ -0,0 +1,24 @@
# Bible Saselang 0.2.12
> **Statut : pré-spécification normative de Saselang V1.**
>
> Cette Bible est la base de conception destinée à la première implémentation du compilateur, de l'interpréteur, du Core, du SDK initial et des outils Saselang V1.
> Elle ne cherche pas à figer définitivement les extensions de V3+ (browser, JVM, JavaScript/TypeScript, packaging mobile, etc.), mais elle doit éviter que les choix de V1 les rendent artificiellement impossibles.
>
> La V2 visera principalement la réécriture/self-hosting de la toolchain V1 en Saselang lui-même. Les extensions majeures de cibles et d'écosystème sont prévues à partir de V3+.
>
> **Révision 0.2.12 :** première distribution multifichier ; fixation de la distinction `is` / `instanceof`, formalisation initiale des casts/downcasts et de la surface de conversion numérique Core, introduction de l'annexe exhaustive des conversions et du modèle de livraison `full` + deltas SemVer.
## Organisation de cette distribution
```text
chapters/ un fichier par chapitre normatif
examples/ un compagnon examples / DO-DON'T par chapitre
annexes/ matrices et références exhaustives séparées
profiles/ vues documentaires par périmètre
MANIFEST.toml manifest de distribution et hashes
```
`001-SUMMARY.md` est l'entrée de navigation principale.
À partir de cette baseline `0.2.12`, une version suivante peut être livrée sous forme de delta SemVer ne contenant que les fichiers réellement ajoutés, modifiés ou supprimés.

67
001-SUMMARY.md Normal file
View File

@@ -0,0 +1,67 @@
# Sommaire — Bible Saselang 0.2.12
## Chapitres
- [0. Statuts normatifs](chapters/000-statuts-normatifs.md)
- [1. Trajectoire d'implémentation](chapters/001-trajectoire-dimplementation.md)
- [2. Principes généraux du langage](chapters/002-principes-generaux-du-langage.md)
- [3. Architecture de compilation](chapters/003-architecture-de-compilation.md)
- [4. Couches de l'écosystème V1](chapters/004-couches-de-lecosysteme-v1.md)
- [5. Types primitifs](chapters/005-types-primitifs.md)
- [6. Types, variables, constantes et scopes](chapters/006-types-variables-constantes-et-scopes.md)
- [7. Types nominaux et fichiers `.saseltype`](chapters/007-types-nominaux-et-fichiers-saseltype.md)
- [8. Classes et `Object`](chapters/008-classes-et-object.md)
- [9. Structs](chapters/009-structs.md)
- [10. Enums algébriques](chapters/010-enums-algebriques.md)
- [11. Tuples](chapters/011-tuples.md)
- [12. Unions](chapters/012-unions.md)
- [13. Interfaces](chapters/013-interfaces.md)
- [14. Generics](chapters/014-generics.md)
- [15. Fonctions, méthodes et `clsmethod`](chapters/015-fonctions-methodes-et-clsmethod.md)
- [16. Dispatch, override et modificateurs](chapters/016-dispatch-override-et-modificateurs.md)
- [17. Construction et destruction](chapters/017-construction-et-destruction.md)
- [18. `Result`, erreurs et exceptions](chapters/018-result-erreurs-et-exceptions.md)
- [19. Contrôle de flux](chapters/019-controle-de-flux.md)
- [20. Opérateurs](chapters/020-operateurs.md)
- [21. Strings, Unicode et encodages](chapters/021-strings-unicode-et-encodages.md)
- [22. Collections et itération](chapters/022-collections-et-iteration.md)
- [23. `Option<T>` et `Nullable<T>`](chapters/023-optiont-et-nullablet.md)
- [24. Casts et conversions](chapters/024-casts-et-conversions.md)
- [25. Lambdas, closures, callables et generators](chapters/025-lambdas-closures-callables-et-generators.md)
- [26. Async et concurrence](chapters/026-async-et-concurrence.md)
- [27. Mémoire, références et `unsafe`](chapters/027-memoire-references-et-unsafe.md)
- [28. `defer` et nettoyage](chapters/028-defer-et-nettoyage.md)
- [29. FFI et ABI](chapters/029-ffi-et-abi.md)
- [30. Réflexion, métadonnées et tests](chapters/030-reflexion-metadonnees-et-tests.md)
- [31. Fichiers source V1](chapters/031-fichiers-source-v1.md)
- [32. Source root, modules et namespaces](chapters/032-source-root-modules-et-namespaces.md)
- [33. Imports et résolution des noms](chapters/033-imports-et-resolution-des-noms.md)
- [34. Packages, identité et collisions de namespaces](chapters/034-packages-identite-et-collisions-de-namespaces.md)
- [35. Manifests et workspaces](chapters/035-manifests-et-workspaces.md)
- [36. SemVer et politique de releases](chapters/036-semver-et-politique-de-releases.md)
- [37. Dépendances et scopes](chapters/037-dependances-et-scopes.md)
- [38. Resolver et lockfile](chapters/038-resolver-et-lockfile.md)
- [39. Features, `module.saselmod` et compilation conditionnelle](chapters/039-features-module-saselmod-et-compilation-conditionnelle.md)
- [40. Targets, plateformes, architectures, ABI, distributions et capabilities](chapters/040-targets-plateformes-architectures-abi-distributions-et-capabilities.md)
- [41. Artifacts, exports, profils et réservation des formats futurs](chapters/041-artifacts-exports-profils-et-reservation-des-formats-futurs.md)
- [42. `main` et `ExitCode`](chapters/042-main-et-exitcode.md)
- [43. Documentation et tests de conformité](chapters/043-documentation-et-tests-de-conformite.md)
- [44. Browser — FUTUR V3+](chapters/044-browser-futur-v3.md)
- [45. Autres backends/cibles — FUTUR V3+](chapters/045-autres-backends-cibles-futur-v3.md)
- [46. Quantique — FUTUR LOINTAIN / RÉSERVÉ](chapters/046-quantique-futur-lointain-reserve.md)
- [47. Concepts rejetés ou déconseillés](chapters/047-concepts-rejetes-ou-deconseilles.md)
- [48. Inventaire des points V1 encore OUVERTS](chapters/048-inventaire-des-points-v1-encore-ouverts.md)
- [49. Éléments V1 RÉSERVÉS mais non obligatoires à implémenter immédiatement](chapters/049-elements-v1-reserves-mais-non-obligatoires-a-implementer-immediatement.md)
- [50. Éléments FUTURS V3+ identifiés](chapters/050-elements-futurs-v3-identifies.md)
- [51. Invariants de conception](chapters/051-invariants-de-conception.md)
- [52. Priorité de spécification après 0.2.9](chapters/052-priorite-de-specification-apres-0-2-9.md)
## Annexes
- [Annexe A — Matrice des conversions numériques](annexes/A-numeric-conversions.md)
## Vues documentaires
- [Language / Compiler Specification](profiles/language-compiler.md)
- [Saselang + Core Specification](profiles/language-core.md)
- [Saselang Platform Documentation](profiles/platform.md)

30
002-DOCUMENTATION-MODEL.md Normal file
View File

@@ -0,0 +1,30 @@
# Modèle documentaire — 0.2.12
La documentation Saselang est organisée en trois périmètres emboîtés.
## Language / Compiler Specification
Décrit ce qu'un compilateur Saselang conforme doit accepter, refuser et produire : syntaxe, système de types, sémantique, contrôle de flux, règles de compilation, interaction avec le Core, targets et lowering contractuel.
## Saselang + Core Specification
Ajoute le Core normatif : types fondamentaux, API des primitives, erreurs, opérateurs, ranges, collections Core et capacités standard.
## Saselang Platform Documentation
Ajoute les SDKs et extensions de plateforme.
## Distribution
Une archive `full` est une baseline complète.
Une archive `delta` future doit déclarer sa `base_version` et ne contenir que les fichiers ajoutés ou modifiés. Les suppressions sont listées dans son manifest.
Le nom recommandé est :
```text
saselang_bible_<version>_full.zip
saselang_bible_<version>_delta_from_<base-version>.zip
```
Cette `0.2.12` est la première baseline multifichier et ne possède donc pas de delta multifichier antérieur.

16
003-CHANGELOG.md Normal file
View File

@@ -0,0 +1,16 @@
# Changelog documentaire — 0.2.12
## 0.2.12
- migration de la Bible monolithique vers une distribution multifichier ;
- ajout d'un fichier compagnon examples / DO-DON'T par chapitre ;
- ajout des vues Language/Compiler, Language+Core et Platform ;
- ajout de l'annexe exhaustive des conversions numériques ;
- `is` figé comme test d'appartenance à une hiérarchie polymorphe ;
- `instanceof` figé comme test de classe runtime exacte, limité aux classes concrètes non abstraites ;
- upcast par assignabilité ; downcast canonique par `is` + refinement ;
- conversions numériques exposées par le Core plutôt que multipliées comme syntaxe compiler-specific ;
- `NumericConversionError` retenu comme nom de travail ;
- règle de non-redondance des variantes de conversion ;
- nom `saturatingRoundToFloatXX()` retenu lorsqu'arrondi et saturation doivent tous deux être annoncés ;
- modèle de livraison documentaire `full` + deltas SemVer.

461
MANIFEST.toml Normal file
View File

@@ -0,0 +1,461 @@
format = 1
version = "0.2.12"
distribution = "full"
base_version = ""
documentation_layout = "multifile"
[[files]]
path = "000-README.md"
sha256 = "54178a0e9d920766859335ae851b5424fe0721344089e926e3df1904e80bb2d5"
[[files]]
path = "001-SUMMARY.md"
sha256 = "231083968ba2895084386113e1337cd5c63315413eb91151327ba588b8c881b9"
[[files]]
path = "002-DOCUMENTATION-MODEL.md"
sha256 = "f939efa7d1379ed263a14a125ca8343ff4f182cda956955b5903f2da99df0a18"
[[files]]
path = "003-CHANGELOG.md"
sha256 = "4048bddd42f8d8102735716e8c1378fc254d2cdc08368e69da683b3ebc205cf3"
[[files]]
path = "annexes/A-numeric-conversions.md"
sha256 = "b2e8d0d1f7fd2773ad4ba5308e41a0c51f48b23b77983759ef8b44b5c6aa70ba"
[[files]]
path = "chapters/000-statuts-normatifs.md"
sha256 = "adad2d9969de674e74b27456088c8ab8287706add7b9b9f4ef25acdb47f98abc"
[[files]]
path = "chapters/001-trajectoire-dimplementation.md"
sha256 = "aec24baf0839bcc421b6d3bb1f4362e967655520250e93b63eee9a0b1c6c1ee4"
[[files]]
path = "chapters/002-principes-generaux-du-langage.md"
sha256 = "375357d732445b3c781121628cc9cabfa01ed1f27bc673143eedc3adbb0db0a1"
[[files]]
path = "chapters/003-architecture-de-compilation.md"
sha256 = "aa8289a8f12124215d050f655a63952d11d158e814cf0e92f7ada7f875c18ed1"
[[files]]
path = "chapters/004-couches-de-lecosysteme-v1.md"
sha256 = "fbdcfb41f140dc94ed068bbfec7f4740b0c9723128e59959127b38275578e286"
[[files]]
path = "chapters/005-types-primitifs.md"
sha256 = "9b313a1adce6f6a12fe2015613603f1e33727e043d56c429afdbf8c60854a792"
[[files]]
path = "chapters/006-types-variables-constantes-et-scopes.md"
sha256 = "a3f4ea068f5273d64842bc8cbf25cecc36aaa73d166cedd74f85af52fa345d67"
[[files]]
path = "chapters/007-types-nominaux-et-fichiers-saseltype.md"
sha256 = "200e87df7e530f58a7bc8d193a857891a56c3594fa7750bf3ae430e2f1af9c7b"
[[files]]
path = "chapters/008-classes-et-object.md"
sha256 = "442c0b0beeb41d9329400b90edb5c8c510b815f319059b8802120c9532e2fe82"
[[files]]
path = "chapters/009-structs.md"
sha256 = "d23b0b4055de2ed32eaef76f534f245a51b7f9fb1030bf73ac2231f3ef858ab3"
[[files]]
path = "chapters/010-enums-algebriques.md"
sha256 = "5743f854fba3a0cd7a539ed97686978ff05e0d84bef0cf446307d3583e0c0fe1"
[[files]]
path = "chapters/011-tuples.md"
sha256 = "19692031e4ac96b4d15dde240033b92cd4051acce58de17e4969b6a5ac2a06fd"
[[files]]
path = "chapters/012-unions.md"
sha256 = "2ba425792989386546f8176cf5937d9256ecbcb5950ec0841989b2888afdeeb6"
[[files]]
path = "chapters/013-interfaces.md"
sha256 = "3787c491751256940deddff1e507988ad028b6cb5aa4f3d48e2c88f75dee9517"
[[files]]
path = "chapters/014-generics.md"
sha256 = "10507bacab272ec59b3f43f018942e7055b9135335e3748698afc3d4a1cf7331"
[[files]]
path = "chapters/015-fonctions-methodes-et-clsmethod.md"
sha256 = "930b4ce52bf59c372bc2c068d13f2c3b55b4b1409a93438a00aff0fed9e6b3b1"
[[files]]
path = "chapters/016-dispatch-override-et-modificateurs.md"
sha256 = "c3072282a152c471e726d485a228e19dc1f34cebb2092fc83354d8ac562b881f"
[[files]]
path = "chapters/017-construction-et-destruction.md"
sha256 = "78808a62bd115245fa56908b742fa38d2125a941a41e0b66d10fcfdca71e8ccc"
[[files]]
path = "chapters/018-result-erreurs-et-exceptions.md"
sha256 = "a3737a880d01f08cd81146f9b9b8c9079c7c22fdec09a207a6bdbc9479c9a7ed"
[[files]]
path = "chapters/019-controle-de-flux.md"
sha256 = "7dd4a4df448145f98f1f3f5adf1727639ebb6f0f62c0167e93d14852fe2e2c1b"
[[files]]
path = "chapters/020-operateurs.md"
sha256 = "c01b09d2274650d8de35cb2a859cf5a313babec355f79474780324126f2713a6"
[[files]]
path = "chapters/021-strings-unicode-et-encodages.md"
sha256 = "a10a2a5afbe0b95353ef9e56a33b329563b0530e3a1ce9dc0fbb1525e472547b"
[[files]]
path = "chapters/022-collections-et-iteration.md"
sha256 = "644c88d2e90a204de64ce8cf941ba876aaac0a35710cbb56a2ff46db09417a6c"
[[files]]
path = "chapters/023-optiont-et-nullablet.md"
sha256 = "237f9c31419a9426965ac9a0ca520dcea116138c588579abc1a40628edfd8db8"
[[files]]
path = "chapters/024-casts-et-conversions.md"
sha256 = "91672400a7681386b71b3ea1d090527a8609637e7b056450af05c993ce6c0f9a"
[[files]]
path = "chapters/025-lambdas-closures-callables-et-generators.md"
sha256 = "62faff3388b0238cdfbb6ff3fafacf7daaf582fa5e5b40723307425e8b081686"
[[files]]
path = "chapters/026-async-et-concurrence.md"
sha256 = "36f936c6af6012d04906c6d6792de589e4d15cbcc28ed45b0538b6a8aabec4ee"
[[files]]
path = "chapters/027-memoire-references-et-unsafe.md"
sha256 = "4dafe27ae8243d38013b3c48ea5abe7e987cecdb4b94d193a0ed318452b16242"
[[files]]
path = "chapters/028-defer-et-nettoyage.md"
sha256 = "0e7bbdf8cd57652fdaa1bbaef734c561910d5bb99a6d4ec216220a2ab3b38a15"
[[files]]
path = "chapters/029-ffi-et-abi.md"
sha256 = "fc395a15a4d5404bd982105fb043a3cac639147cccaf7722fe640aaad17b573c"
[[files]]
path = "chapters/030-reflexion-metadonnees-et-tests.md"
sha256 = "818bf11cbafa7b0708dbff2d474abce0abf6e533603d593dcd519c49796d8d8f"
[[files]]
path = "chapters/031-fichiers-source-v1.md"
sha256 = "0d978fa1a4e30d71e2bf6634c67ac54194c48640861fbb3e5d3c337aa366fd83"
[[files]]
path = "chapters/032-source-root-modules-et-namespaces.md"
sha256 = "ce5077f0475a161221919aa7f15f1c4bc0585e627070e07b99aeabcedf3a683d"
[[files]]
path = "chapters/033-imports-et-resolution-des-noms.md"
sha256 = "9b8a4cef4101d35b06235345865f5f7179a8e8219c6e363fedd839251c6eb70e"
[[files]]
path = "chapters/034-packages-identite-et-collisions-de-namespaces.md"
sha256 = "e2c69dca0f46e1cc88d47531d2b605f5ffe04a5151a7a73e6e75e6f3e67ff050"
[[files]]
path = "chapters/035-manifests-et-workspaces.md"
sha256 = "ddf32952d72bcaf592324295e6c69c0e43f85547e392d1ef22a67cc7aa763463"
[[files]]
path = "chapters/036-semver-et-politique-de-releases.md"
sha256 = "d96c4df73e59e76510369a15032c4e1994ebc259309177c36548449ea62112be"
[[files]]
path = "chapters/037-dependances-et-scopes.md"
sha256 = "a65d4e69b5a92ca9d04e2f2f83f856c4b9b12790f5b8ea64d2c7b3d21bdb68d4"
[[files]]
path = "chapters/038-resolver-et-lockfile.md"
sha256 = "b1312987120a5b25e774af5ae353f112730c68ae81610a818711a12886c3a4f9"
[[files]]
path = "chapters/039-features-module-saselmod-et-compilation-conditionnelle.md"
sha256 = "ab3298e8a5402844c61c283fd46c57f1727e2e6a19af7d2d89c70549742f1032"
[[files]]
path = "chapters/040-targets-plateformes-architectures-abi-distributions-et-capabilities.md"
sha256 = "a07c118f3ed3dff0fd643e3bcd2334facb22740075100dff2c71384188dcb062"
[[files]]
path = "chapters/041-artifacts-exports-profils-et-reservation-des-formats-futurs.md"
sha256 = "9dd1096b0488d176da8cf48dedb121427c1acf3313509f0da13d8988ae520b87"
[[files]]
path = "chapters/042-main-et-exitcode.md"
sha256 = "57499c713a618e5ff52a3186072b3694c1e1144a577589becb8a9a80fae7b88f"
[[files]]
path = "chapters/043-documentation-et-tests-de-conformite.md"
sha256 = "8c522c7c6ded5d39dc649c1217dd625ba482a25ec301663e1867857d9b4b1fc5"
[[files]]
path = "chapters/044-browser-futur-v3.md"
sha256 = "cf9f95b7c07b2c78c86f07bf6093641645e11e67526311f13a21638ca3f47b8d"
[[files]]
path = "chapters/045-autres-backends-cibles-futur-v3.md"
sha256 = "c7ff453312bf0b6db2375c98461f6c722286ab3816512d67509b85bc665cd87e"
[[files]]
path = "chapters/046-quantique-futur-lointain-reserve.md"
sha256 = "b538c8e32e3376386e802de174f4a50ff14ca4262969ab065a89bbcb4b40fbe5"
[[files]]
path = "chapters/047-concepts-rejetes-ou-deconseilles.md"
sha256 = "eb037983de591edeff740513d98285511bdc60da8dae38f28031dc04902cab1f"
[[files]]
path = "chapters/048-inventaire-des-points-v1-encore-ouverts.md"
sha256 = "81234f81aeefa33993b37437ba9fefe83dd6f0286aa527b71a475fab55f294ce"
[[files]]
path = "chapters/049-elements-v1-reserves-mais-non-obligatoires-a-implementer-immediatement.md"
sha256 = "6451dbf71d2d53e1642c9a33cf1dd109351df926ee2b7f4859c8151058c8222a"
[[files]]
path = "chapters/050-elements-futurs-v3-identifies.md"
sha256 = "69f6efc022b684d8401f0ae69ce70530d4bc607eed155182961db74ebbd102e8"
[[files]]
path = "chapters/051-invariants-de-conception.md"
sha256 = "7c4ba9a3982e37630926666be3a4d4f450fb8c6508605e73a44c0d4a6ac8330e"
[[files]]
path = "chapters/052-priorite-de-specification-apres-0-2-9.md"
sha256 = "c25d105588e2a0ab6dc272887dfd1c7e8fc6ca279c72e72661f140d65aea6406"
[[files]]
path = "examples/000-statuts-normatifs-examples.md"
sha256 = "603326859af5152e7b5097b85acf14b464d8f6e44dd61ee97da1dbfda5ff19c3"
[[files]]
path = "examples/001-trajectoire-dimplementation-examples.md"
sha256 = "dc9c9dae4d680d9142688cb9c1f6471f294f3837f69eae287f6cc76c192b8d93"
[[files]]
path = "examples/002-principes-generaux-du-langage-examples.md"
sha256 = "0b8662b49f5cec5a396339fb7955b5c94e5f9d3e8ae378a7d7f4bdba1cc5d141"
[[files]]
path = "examples/003-architecture-de-compilation-examples.md"
sha256 = "d2a5578e5786ae43dc6f5aa8a2991bf0722a387eb1bbf8edb753d0dece9efef0"
[[files]]
path = "examples/004-couches-de-lecosysteme-v1-examples.md"
sha256 = "d77a0dec5925d52eda92ff096eea9c89e17344f954fc873b2748e96159f11304"
[[files]]
path = "examples/005-types-primitifs-examples.md"
sha256 = "7f76514d40634957c012225d1505e4f3897e4dc740d2f4bc10faaa9cfe74da91"
[[files]]
path = "examples/006-types-variables-constantes-et-scopes-examples.md"
sha256 = "aafae93d041b6ff7a1904b38fdf32edd108d8f3e2a4448938789acee22cead95"
[[files]]
path = "examples/007-types-nominaux-et-fichiers-saseltype-examples.md"
sha256 = "68f231240b8b2aba706af1c4f31f0ee03031f077808fcc7dce106377cecacf24"
[[files]]
path = "examples/008-classes-et-object-examples.md"
sha256 = "911176c0a75bfe34087d910777b5584b4a2a297ea55d967d47c2c2ce2ee31f28"
[[files]]
path = "examples/009-structs-examples.md"
sha256 = "166489ef32db9faf73e490671664c785c700bc945ee13208d29ee54481172d02"
[[files]]
path = "examples/010-enums-algebriques-examples.md"
sha256 = "315d85a96f31809ce5a600e262d3719ecfb735ac47603cccd6c7f7af2cdde79b"
[[files]]
path = "examples/011-tuples-examples.md"
sha256 = "254dab32d5e9a21f4a9849894bac2d7f946a1c113e76f3c40388fe35dd87229f"
[[files]]
path = "examples/012-unions-examples.md"
sha256 = "68bf56ae82d3a82d4c306c44d8be979c3d96342e1d0d6c6d6a864a7dee7a7110"
[[files]]
path = "examples/013-interfaces-examples.md"
sha256 = "eaa95dd7a8e4a6d48e132a2e092d8919c70810678adfc4adfcb0144a2ee8fd82"
[[files]]
path = "examples/014-generics-examples.md"
sha256 = "31e091f9e765ddf75ed4317871814dd516447d37f96332de4190117e24acdc2d"
[[files]]
path = "examples/015-fonctions-methodes-et-clsmethod-examples.md"
sha256 = "d200b80b6aa44592fc402e31905d2fad39c6a2c8af72141b62bd50d18327d85d"
[[files]]
path = "examples/016-dispatch-override-et-modificateurs-examples.md"
sha256 = "1b0692a23aea7f987413ab9e1b28b47319b5b0bc3b4bbc01da6427e626a0ab6e"
[[files]]
path = "examples/017-construction-et-destruction-examples.md"
sha256 = "b5007805d0f49736b0ede122549bc25ccc8324152e391781694daa692df1b1a4"
[[files]]
path = "examples/018-result-erreurs-et-exceptions-examples.md"
sha256 = "07ccc65d0f0da12df0b3693931355791a8f10f92b35ff7513f54fd8fa948b9c2"
[[files]]
path = "examples/019-controle-de-flux-examples.md"
sha256 = "1932134c40c28ccfc8e412737fa41a3bf7b62230dfaf19b1f8ba9c874897e215"
[[files]]
path = "examples/020-operateurs-examples.md"
sha256 = "d3dfdb43d3b22ea49f26d86605a37ebe63bdfd03c1ca281f40b113e50bc7dc47"
[[files]]
path = "examples/021-strings-unicode-et-encodages-examples.md"
sha256 = "789523370776c97890bfec3969c04e203ec27580778f169eb78fc00503e51ff3"
[[files]]
path = "examples/022-collections-et-iteration-examples.md"
sha256 = "264f10c49cc8743d99709ff6449d7fc1b0ed89825972acbd7619e99167278a13"
[[files]]
path = "examples/023-optiont-et-nullablet-examples.md"
sha256 = "4de6187045e9159fd5300219632b79ecdaa558d2c001ff40dac131e31e2d3e19"
[[files]]
path = "examples/024-casts-et-conversions-examples.md"
sha256 = "669d64eecfb93484c44d37a4e7ea9089fec6f5369ecd0f51bcdd0e42d478f5ee"
[[files]]
path = "examples/025-lambdas-closures-callables-et-generators-examples.md"
sha256 = "e423a0e4f204187ec7e4082d16ad1c69178009b213730764da3a79318e338b32"
[[files]]
path = "examples/026-async-et-concurrence-examples.md"
sha256 = "879445bf8779a0b895fa1e6014a1ac404c1b9c94138edeab8dfc3eeff08e6197"
[[files]]
path = "examples/027-memoire-references-et-unsafe-examples.md"
sha256 = "9ae88eb5f6392411da9c1a60b5c1026342c2c73e2e57516a37535f46562fcf8c"
[[files]]
path = "examples/028-defer-et-nettoyage-examples.md"
sha256 = "1f9d7ee762391b7cd49811cefe550825ff086160d53a268f37f9eccbb40c1acd"
[[files]]
path = "examples/029-ffi-et-abi-examples.md"
sha256 = "32dc3da8d95ab38f5c4beaba7d86a316856f0c18ddf867d915a80a004eced7fc"
[[files]]
path = "examples/030-reflexion-metadonnees-et-tests-examples.md"
sha256 = "44fb73994d7d26d67ad9cc1274c8f3ef526b1516696807c59776ad0a9444d33d"
[[files]]
path = "examples/031-fichiers-source-v1-examples.md"
sha256 = "9741c8a0dc0e998e006e09b01d4b215e0b61a24282d334bf6a422c78a59c01fd"
[[files]]
path = "examples/032-source-root-modules-et-namespaces-examples.md"
sha256 = "b998d3b625c15b9481c2f983c5e7577d32f95b441d839663f1d3e586dc774722"
[[files]]
path = "examples/033-imports-et-resolution-des-noms-examples.md"
sha256 = "8c2e4f9777d2fd051bb739a9aa34ab6ba7bbc0fee7f9beef739d98d2c7bc6bde"
[[files]]
path = "examples/034-packages-identite-et-collisions-de-namespaces-examples.md"
sha256 = "825e5375e64e3e395d7d5dd3409b2bbcca17a54eef49474aa5041f2374902f6b"
[[files]]
path = "examples/035-manifests-et-workspaces-examples.md"
sha256 = "7541fa0ce1a82bb7f3911f7e4c63d45c1b018f58e5e5a1d05a1d0bcc7231e8a2"
[[files]]
path = "examples/036-semver-et-politique-de-releases-examples.md"
sha256 = "fc7ced4d0441b0a3ace89da6476dad95ae88a922e4258e239ef207f96296bfe0"
[[files]]
path = "examples/037-dependances-et-scopes-examples.md"
sha256 = "fbb49ee7ab46c36494846fb5de6f031a924ef130dcbe3fa8a146061220234a07"
[[files]]
path = "examples/038-resolver-et-lockfile-examples.md"
sha256 = "538c464ebf90fe62caa293bed81db33c0c2a83ad5212d2376f13c68d01bcac0c"
[[files]]
path = "examples/039-features-module-saselmod-et-compilation-conditionnelle-examples.md"
sha256 = "b94143a8a166341c5b9d7a4d5d1f3d4e30d4246dace2996b04ba5168edde2069"
[[files]]
path = "examples/040-targets-plateformes-architectures-abi-distributions-et-capabilities-examples.md"
sha256 = "7d06abcbbdad7bda07bf490f5a8847ad7cfb8634d9479c9b1302f173e2366793"
[[files]]
path = "examples/041-artifacts-exports-profils-et-reservation-des-formats-futurs-examples.md"
sha256 = "65b85a25d9caed6955864a85dff17cdedfdef56cb27f77dbe133837738850999"
[[files]]
path = "examples/042-main-et-exitcode-examples.md"
sha256 = "5e863daae3593ba7e39da2fbee6b1721988d8edf82f5abdb1a0ca14520d54e69"
[[files]]
path = "examples/043-documentation-et-tests-de-conformite-examples.md"
sha256 = "a0b99ab645787b6b0bbb2e83041888cfe2782fae0a9064fa2bfa5907b817b819"
[[files]]
path = "examples/044-browser-futur-v3-examples.md"
sha256 = "b1b63def42c8abebe943c89f618e16bcabd56e050bee760c9ba3b063dcf951d8"
[[files]]
path = "examples/045-autres-backends-cibles-futur-v3-examples.md"
sha256 = "92a6269861d51d9364eb76d4533cecf8ea36e8111f257b96f916d6fd63d91dbd"
[[files]]
path = "examples/046-quantique-futur-lointain-reserve-examples.md"
sha256 = "da2b95b3adf5431e4c32dcd631fd380a04b4173c98b2c638cad2e5f4564e131b"
[[files]]
path = "examples/047-concepts-rejetes-ou-deconseilles-examples.md"
sha256 = "0c347c9c622096fe026a76671c88258e37896b4e735b33fac2d5b01cc9a73fed"
[[files]]
path = "examples/048-inventaire-des-points-v1-encore-ouverts-examples.md"
sha256 = "6b9ce1377041b4bfd40a48eab0bb6a40b852e8c1c7cedde89a6329b6c495c192"
[[files]]
path = "examples/049-elements-v1-reserves-mais-non-obligatoires-a-implementer-immediatement-examples.md"
sha256 = "0fde247c9612c8ab74260c948c6d0d9a1648388dbfa5794fb7040a7ecaf7184e"
[[files]]
path = "examples/050-elements-futurs-v3-identifies-examples.md"
sha256 = "49fa7b31de952d996fa8384ce1addc22a12f9d7a05f46d651e1eb2cf055d1c55"
[[files]]
path = "examples/051-invariants-de-conception-examples.md"
sha256 = "491525c8e45c5ef71f4bcc0420d3757ac004f5da47b5a21a29c5088f539bff68"
[[files]]
path = "examples/052-priorite-de-specification-apres-0-2-9-examples.md"
sha256 = "a663bdf02646d77ed5d870a0a8c24c477f4067ccc163e1c6ac55d46b368f539d"
[[files]]
path = "profiles/language-compiler.md"
sha256 = "705758ab8d40838bd9dc119e90183e69013258c028467d66df2678d676f915f1"
[[files]]
path = "profiles/language-core.md"
sha256 = "42f503a3ed5fa77e88c218c46523e4ef1b72e4104a2f8471597b4b900d492567"
[[files]]
path = "profiles/platform.md"
sha256 = "19440a7628f2e26d15fa8d33a4f0e5b8e5c936b3e23e293a9a27f16d2ff34322"

308
annexes/A-numeric-conversions.md Normal file
View File

@@ -0,0 +1,308 @@
# Saselang — Annexe A — Matrice des conversions numériques
**Version documentaire : 0.2.12. Statut : inventaire de conception Core, destiné à devenir normatif après validation.**
Cette annexe est le listing exhaustif de travail des conversions numériques Core.
Son objectif est d'énumérer le maximum de conversions numériques sémantiquement distinctes sans introduire d'alias ou de doublons inutiles.
## A.1. Répartition des responsabilités
Les conversions numériques sont exposées comme capacités de l'API Core des primitives. Elles ne deviennent pas chacune une construction grammaticale du compilateur.
```text
Bible langage / compilateur
définit les règles de typage, d'appel, d'intrinsic, de target et de lowering
Core
expose les membres numériques concrets
ex. int32::tryToInt8(), float64::tryRoundToFloat32()
Annexe Core
liste exhaustivement les opérations disponibles par paire de types
Compilateur / Sase IR / backend
valide et abaisse l'opération Core sans que chaque nom devienne de la grammaire
```
Une capacité Core peut être conditionnée par un target ou une plateforme lorsque cela est réellement nécessaire. L'absence d'une capacité demandée doit être diagnostiquée à la compilation pour le target choisi, et non découverte tardivement dans le backend.
Les conversions numériques fondamentales entre primitives standard sont destinées à constituer le socle Core commun ; le mécanisme de capacités existe surtout pour les opérations qui ne peuvent raisonnablement pas être garanties partout.
## A.2. Règle de non-redondance
Une variante n'existe que si elle apporte une sémantique observable différente de l'opération canonique déjà disponible pour la paire source/destination.
Exemple :
```saselang
int8 value = ...;
int32 larger = value::toInt32();
```
Puisque toutes les valeurs `int8` sont représentables exactement dans `int32`, les formes suivantes n'ont aucune raison d'exister :
```text
tryToInt32()
saturateToInt32()
wrapToInt32()
```
En revanche, pour `int32 -> int8`, `tryToInt8()`, `saturateToInt8()` et `wrapToInt8()` ont trois contrats différents et peuvent coexister.
## A.3. Nomenclature générale
| Code | Famille | Contrat |
|---|---|---|
| `T` | `toTarget()` | Exacte et totale pour toutes les valeurs valides du type source. |
| `E` | `tryToTarget()` | Exacte pour la valeur courante ; retourne `Err` si l'exactitude ou la représentabilité échoue. |
| `R` | `roundToTarget()` | Perte de précision explicitement acceptée ; conversion totale pour cette paire de types. |
| `TR` | `tryRoundToTarget()` | Arrondi explicitement accepté, mais la valeur peut être hors du domaine destination. |
| `S` | `saturateToTarget()` | Conversion totale par saturation lorsqu'aucun arrondi supplémentaire n'est nécessaire. |
| `SR` | `saturatingRoundToTarget()` | Arrondi canonique + saturation explicites pour une destination flottante lorsque les deux peuvent être nécessaires. |
| `W` | `wrapToTarget()` | Conversion entière modulo `2^N`, avec interprétation selon le type entier destination. |
| `—` | aucune | Même type ou opération sans sémantique distincte utile. |
`NumericConversionError` est retenu comme nom de travail Core. Il pourra être renommé avant stabilisation de la spécification si nécessaire.
Les formes `try...` retournent conceptuellement :
```saselang
Result<Target, NumericConversionError>
```
Aucune de ces opérations n'autorise une conversion implicite entre deux variables déjà typées.
## A.4. Flottants : hypothèses de représentation
| Type | Précision significative `p` | Exposant maximal fini |
|---|---|---|
| `float16` | 11 bits | 15 |
| `float32` | 24 bits | 127 |
| `float64` | 53 bits | 1023 |
| `float128` | 113 bits | 16383 |
Les conversions avec arrondi utilisent par défaut la règle canonique **round to nearest, ties to even**. Cette règle ne dépend ni du linter, ni du profil, ni du backend.
## A.5. Entier -> entier
Légende :
- `T` = `toTarget()` uniquement ;
- `E+S+W` = `tryToTarget()` + `saturateToTarget()` + `wrapToTarget()`.
| Source \ Destination | int8 | int16 | int32 | int64 | int128 | int256 | uint8 | uint16 | uint32 | uint64 | uint128 | uint256 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| int8 | — | T | T | T | T | T | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| int16 | E+S+W | — | T | T | T | T | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| int32 | E+S+W | E+S+W | — | T | T | T | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| int64 | E+S+W | E+S+W | E+S+W | — | T | T | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| int128 | E+S+W | E+S+W | E+S+W | E+S+W | — | T | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| int256 | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | — | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W |
| uint8 | E+S+W | T | T | T | T | T | — | T | T | T | T | T |
| uint16 | E+S+W | E+S+W | T | T | T | T | E+S+W | — | T | T | T | T |
| uint32 | E+S+W | E+S+W | E+S+W | T | T | T | E+S+W | E+S+W | — | T | T | T |
| uint64 | E+S+W | E+S+W | E+S+W | E+S+W | T | T | E+S+W | E+S+W | E+S+W | — | T | T |
| uint128 | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | T | E+S+W | E+S+W | E+S+W | E+S+W | — | T |
| uint256 | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | E+S+W | — |
Règles :
- si le domaine source est entièrement inclus dans le domaine destination, seule la forme `to...` existe ;
- sinon `tryTo...` effectue une conversion exacte conditionnelle ;
- `saturateTo...` borne à `Target::Min` / `Target::Max` ; pour un signé vers non signé, toute valeur négative sature à `0` ;
- `wrapTo...` utilise une définition mathématique modulo `2^N`, indépendante de la représentation machine du backend ;
- aucun wrapping ni saturation n'est implicite.
## A.6. Entier -> flottant
Légende :
- `T` = `toFloatXX()` uniquement ;
- `E+R` = `tryToFloatXX()` + `roundToFloatXX()` ;
- `E+TR+SR` = `tryToFloatXX()` + `tryRoundToFloatXX()` + `saturatingRoundToFloatXX()`.
| Source \ Destination | float16 | float32 | float64 | float128 |
|---|---|---|---|---|
| int8 | T | T | T | T |
| int16 | E+R | T | T | T |
| int32 | E+TR+S | E+R | T | T |
| int64 | E+TR+S | E+R | E+R | T |
| int128 | E+TR+S | E+R | E+R | E+R |
| int256 | E+TR+S | E+TR+S | E+R | E+R |
| uint8 | T | T | T | T |
| uint16 | E+TR+S | T | T | T |
| uint32 | E+TR+S | E+R | T | T |
| uint64 | E+TR+S | E+R | E+R | T |
| uint128 | E+TR+S | E+TR+S | E+R | E+R |
| uint256 | E+TR+S | E+TR+S | E+R | E+R |
Contrats :
- `toFloatXX()` existe seulement si **toute** valeur source est exactement représentable ;
- `tryToFloatXX()` exige une représentation exacte de la valeur courante ;
- `roundToFloatXX()` existe seulement lorsque toute valeur source reste dans le domaine fini destination, mais qu'une perte de précision peut être nécessaire ;
- `tryRoundToFloatXX()` accepte l'arrondi canonique mais retourne `Err` si la magnitude finie dépasse le domaine destination ;
- `saturatingRoundToFloatXX()` est réservé aux paires pour lesquelles un débordement de domaine est possible : une valeur finie trop grande est bornée au plus grand fini de même signe, puis la précision destination s'applique selon l'arrondi canonique ;
- il n'existe pas de `wrapToFloatXX()`.
Exemple distinct :
```saselang
int64 value = ...;
Result<float64, NumericConversionError> exact = value::tryToFloat64();
float64 approximated = value::roundToFloat64();
```
`tryToFloat64()` et `roundToFloat64()` ne sont pas des alias : le premier refuse toute perte de précision, le second l'accepte explicitement.
## A.7. Flottant -> flottant
Légende :
- `T` = `toFloatXX()` uniquement ;
- `E+TR+SR` = `tryToFloatXX()` + `tryRoundToFloatXX()` + `saturatingRoundToFloatXX()`.
| Source \ Destination | float16 | float32 | float64 | float128 |
|---|---|---|---|---|
| float16 | — | T | T | T |
| float32 | E+TR+S | — | T | T |
| float64 | E+TR+S | E+TR+S | — | T |
| float128 | E+TR+S | E+TR+S | E+TR+S | — |
Règles :
- l'élargissement de format est exact au niveau de la valeur IEEE et utilise uniquement `toFloatXX()` ;
- la réduction de format propose `tryToFloatXX()` pour exiger l'exactitude, `tryRoundToFloatXX()` pour accepter la perte de précision mais pas le débordement fini, et `saturatingRoundToFloatXX()` pour obtenir une opération totale sur le domaine flottant ;
- `NaN`, `+Infinity`, `-Infinity`, `+0` et `-0` restent des catégories IEEE valides dans la destination ;
- `saturatingRoundToFloatXX()` ne transforme pas une infinité en valeur finie puisque l'infinité est elle-même représentable dans le format destination ; la saturation explicite concerne les valeurs **finies** hors du domaine fini destination ;
- la conservation exacte du payload binaire d'un `NaN` n'est pas garantie par une conversion de valeur ; elle relève d'un éventuel contrat binaire distinct et de `bitcast` lorsque les tailles sont compatibles.
## A.8. Flottant -> entier : inventaire des politiques
Il n'existe jamais de simple `toIntXX()` ou `toUintXX()` depuis un flottant.
La conversion doit annoncer à la fois la politique de passage du réel à l'entier et, lorsque cela est pertinent, la politique de dépassement de domaine.
### A.8.1. Politique mathématique
| Famille | Sens |
|---|---|
| `Exact` | Accepte uniquement une valeur flottante finie déjà mathématiquement entière. |
| `Floor` | Plus grand entier mathématique inférieur ou égal. |
| `Ceil` | Plus petit entier mathématique supérieur ou égal. |
| `Round` | Nearest, ties to even. |
| `Truncate` | Suppression de la partie fractionnaire, donc direction zéro. |
### A.8.2. Politique de domaine destination
| Politique | Forme | Comportement |
|---|---|---|
| Checked | `try<Policy>ToTarget()` | `Err` sur `NaN`, infinité ou résultat hors plage. |
| Saturating | `trySaturating<Policy>ToTarget()` | `Err` sur `NaN`; les infinités et résultats hors plage saturent aux bornes destination. |
| Wrapping | `tryWrapping<Policy>ToTarget()` | `Err` sur `NaN` et infinité; les résultats entiers finis sont réduits modulo `2^N`. |
La famille complète potentiellement distincte pour une destination entière donnée est donc :
```saselang
value::tryExactToInt32()
value::tryFloorToInt32()
value::tryCeilToInt32()
value::tryRoundToInt32()
value::tryTruncateToInt32()
value::trySaturatingExactToInt32()
value::trySaturatingFloorToInt32()
value::trySaturatingCeilToInt32()
value::trySaturatingRoundToInt32()
value::trySaturatingTruncateToInt32()
value::tryWrappingExactToInt32()
value::tryWrappingFloorToInt32()
value::tryWrappingCeilToInt32()
value::tryWrappingRoundToInt32()
value::tryWrappingTruncateToInt32()
```
La même famille est applicable aux douze destinations entières `int8..int256` / `uint8..uint256` et aux quatre sources flottantes.
Cette section est volontairement exhaustive : lors de la stabilisation Core, certaines combinaisons pourront être supprimées si elles n'apportent aucune valeur pratique ou si une composition Core unique est préférée. Elles ne devront en revanche jamais être remplacées par une opération ambiguë.
### A.8.3. Matrice flottant -> entier
Toutes les paires source/destination partagent actuellement le même ensemble de politiques candidates ; la table sert à garantir qu'aucun type n'est oublié.
| Source \ Destination | int8 | int16 | int32 | int64 | int128 | int256 | uint8 | uint16 | uint32 | uint64 | uint128 | uint256 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| float16 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 |
| float32 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 |
| float64 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 |
| float128 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 | F15 |
`F15` désigne les 15 opérations candidates listées en A.8.2 : 5 politiques mathématiques × 3 politiques de domaine.
Cas particuliers :
- `+0` et `-0` produisent l'entier zéro lorsque l'opération choisie réussit ;
- `NaN` n'a jamais de conversion entière implicite ni de valeur saturée/wrappée arbitraire ;
- le wrapping est défini sur le résultat entier mathématique fini après application de `Exact/Floor/Ceil/Round/Truncate` ;
- pour une destination non signée, la saturation d'une valeur négative aboutit à `0` ;
- pour une destination signée, la saturation utilise `Target::Min` / `Target::Max`.
## A.9. `bitcast` reste hors de cette matrice
`bitcast<T>(value)` n'est pas une conversion numérique. Il conserve les bits et change leur interprétation sous les contraintes de taille et de validité déjà définies par le langage.
Il ne constitue jamais une alternative implicite à `to...`, `try...`, `round...`, `saturate...` ou `wrap...`.
## A.10. Typage contextuel des littéraux
Le typage contextuel d'un littéral reste distinct de toute conversion de valeur déjà typée.
```saselang
int32 a = 42; // contextualisation du littéral
int8 small = ...;
int32 b = small; // ERROR : pas de conversion implicite
int32 c = small::toInt32(); // OK
```
## A.11. Core, targets et capacités
Les membres de conversion appartiennent au Core des primitives. Le compilateur doit pouvoir reconnaître leur contrat via les métadonnées/Core intrinsics nécessaires sans transformer chaque membre en syntaxe spéciale.
Une opération Core peut être :
- universelle dans le profil Core minimal ;
- disponible par émulation logicielle même sans instruction machine native ;
- ou conditionnée par une capacité target lorsqu'elle dépend réellement d'une plateforme/backend.
Une optimisation matérielle ne constitue pas, à elle seule, une raison de rendre une opération absente : une implémentation logicielle conforme est préférable lorsqu'elle est raisonnable.
## A.12. Hiérarchie documentaire cible
La documentation Saselang est destinée à être organisée par niveaux :
```text
Language / Compiler Specification
ce que le compilateur doit accepter, refuser et produire
Saselang + Core Specification
langage + environnement Core normatif
Saselang Platform Documentation
langage + Core + SDKs + extensions de plateforme
```
À partir de `1.0.0-alpha`, la Bible sera distribuée sous forme d'une archive ZIP structurée avec sommaire, chapitres séparés, exemples/DO-DON'T par chapitre et annexes référencées.
## A.13. Points encore à valider
Les points suivants restent volontairement ouverts avant de rendre cette annexe normative :
1. confirmer la nomenclature exacte des formes composées `trySaturating...` et `tryWrapping...` pour `float -> integer` ;
2. décider si les 15 opérations `float -> integer` doivent réellement être exposées directement ou si certaines doivent être obtenues par composition d'opérations Core sans créer d'alias sémantique ;
3. préciser le contrat observable des payloads NaN lors des conversions `float -> float` ;
4. définir les codes et informations minimales de `NumericConversionError` ;
5. classer explicitement les capacités numériques en Core minimal obligatoire ou capacité conditionnelle de target.

13
chapters/000-statuts-normatifs.md Normal file
View File

@@ -0,0 +1,13 @@
# 0. Statuts normatifs
La Bible 0.2.x utilise les statuts suivants.
- **V1 REQUIS — FIGÉ** : comportement attendu de Saselang V1 et suffisamment défini pour être implémenté.
- **V1 REQUIS — À FINALISER** : fonctionnalité nécessaire à V1, mais dont une partie de la syntaxe ou de la sémantique doit encore être décidée avant le début de son implémentation définitive.
- **V1 RÉSERVÉ** : nom, mot-clé, extension ou point d'architecture réservé dès V1 pour préserver la compatibilité, sans obligation de livrer sa fonctionnalité complète.
- **FUTUR V3+** : orientation d'architecture ou fonctionnalité envisagée après la phase de self-hosting ; elle peut encore évoluer.
- **REJETÉ** : mécanisme explicitement écarté de la conception actuelle.
Une section **V1 REQUIS — À FINALISER** n'est pas une permission de laisser une sémantique indéfinie dans le compilateur V1 : elle constitue une tâche de spécification à fermer avant ou pendant le chantier correspondant.
---

87
chapters/001-trajectoire-dimplementation.md Normal file
View File

@@ -0,0 +1,87 @@
# 1. Trajectoire d'implémentation
## 1.1 V1 — V1 REQUIS — FIGÉ
La V1 constitue le premier environnement réellement utilisable de Saselang.
Objectifs :
```text
frontend complet
lexer
parser
AST
analyse sémantique
HIR
Sase IR
interpréteur
a backend LLVM
Core V1
SDK initial
manifests et workspaces
gestion des dépendances
outils initiaux
```
Le compilateur V1 sera écrit dans un langage existant. Le choix entre Rust, Java ou une combinaison avec des générateurs tels que Flex/Bison ou équivalents reste un choix d'implémentation, pas une propriété du langage Saselang.
LLVM est le premier backend compilé de V1.
La conception de Saselang ne doit cependant pas faire de LLVM une dépendance sémantique du frontend.
## 1.2 Couverture LLVM — V1 REQUIS — FIGÉ EN PRINCIPE
Le backend natif V1 doit rester suffisamment générique pour exploiter les architectures, formats objet et capacités que LLVM peut représenter.
Cela ne signifie pas que toute cible connue de LLVM est automatiquement une cible officiellement supportée de bout en bout par Saselang V1 : une cible complète peut également nécessiter un ABI, un linker, un sysroot, un runtime et des bibliothèques de plateforme compatibles.
Une cible LLVM non validée peut donc être :
```text
représentable par le backend
mais non officiellement supportée par la toolchain Saselang
```
## 1.3 V2 — SELF-HOSTING
La V2 reste également une génération interne. Elle a pour objectif principal la réécriture/self-hosting du compilateur, de l'interpréteur et des outils en Saselang. Des corrections architecturales incompatibles avec V1 restent acceptables si elles sont nécessaires et documentées.
La V2 a pour objectif principal de réécrire progressivement en Saselang les composants réalisés en V1 :
```text
compiler frontend
semantic analysis
Sase IR
interpreter
tooling
package/build tooling
Core/SDK lorsque pertinent
```
La V2 est d'abord une étape de validation du langage par lui-même, pas une excuse pour redéfinir arbitrairement la sémantique V1.
## 1.4 V3+ — FUTUR V3+
La première distribution générale du compilateur et de l'écosystème Saselang est envisagée à partir de V3 ou d'une génération ultérieure. C'est à partir de cette baseline publique que la compatibilité source, binaire et de tooling devra être protégée beaucoup plus strictement.
À partir de V3+, les efforts pourront se concentrer sur les autres environnements et backends :
```text
browser runtime / extension
browser chunks/bundling
WebAssembly
JVM
JavaScript
TypeScript
Android packaging
iOS packaging
backends/ABI supplémentaires
outillage avancé
cibles spécialisées
```
Les décisions browser de cette Bible sont donc des orientations de compatibilité, pas la spécification finale du browser runtime.
---

196
chapters/002-principes-generaux-du-langage.md Normal file
View File

@@ -0,0 +1,196 @@
# 2. Principes généraux du langage
## 2.1 Philosophie — V1 REQUIS — FIGÉ
Saselang vise un langage :
- fortement et statiquement typé ;
- explicite ;
- lisible ;
- déterministe ;
- performant ;
- portable ;
- avec peu de magie ;
- sans complexité cachée de type C++ ;
- sans exposition systématique à l'utilisateur d'un modèle de lifetimes façon Rust ;
- sans garbage collector obligatoire pour les cibles natives ;
- sans retours implicites ;
- sans préprocesseur textuel ;
- sans multiplication de syntaxes synonymes.
Principe directeur :
> **boring but working** : une règle stable et prévisible vaut mieux qu'une syntaxe plus courte mais ambiguë.
## 2.2 Mots-clés — V1 REQUIS — FIGÉ
Les mots-clés du langage sont en anglais.
La documentation de référence peut exister en français et en anglais.
Les mots utilisés par Saselang, les mots réservés pour une évolution future et une liste `reserved-foreign` issue des grands langages restent interdits comme identifiants utilisateur. Ces catégories peuvent recevoir des diagnostics différents sans changer cette interdiction.
`dowhile`, `elseif` et `in` sont des mots-clés actifs Saselang. La forme historique `do ... while` n'existe pas ; `do` reste néanmoins interdit comme identifiant et appartient à `reserved-foreign`. `elif` est également interdit/réservé comme mot étranger : Saselang utilise uniquement `elseif`. Les mots historiques ou étrangers correspondant à des doublons rejetés tels que `until`, `repeat`, `unless` ou `loop` restent réservables dans `reserved-foreign` sans recevoir de sémantique Saselang.
## 2.3 Une sémantique par concept — V1 REQUIS — FIGÉ
Saselang évite les alias syntaxiques ne produisant aucune différence sémantique réelle.
Exemples actuellement rejetés :
```text
and comme alias de &&
or comme alias de ||
=== en plus de l'identité explicite
++ et --
ternaire ?: si les formes productrices de `match`/`if` avec `emit` couvrent le besoin
```
Deux formes ne coexistent que lorsqu'elles représentent réellement des comportements différents, par exemple :
```text
&& / || short-circuit
& / | / ^ logique eager sur bool
```
## 2.4 Sémantique indépendante du target — V1 REQUIS — FIGÉ
Une cible peut changer la représentation physique d'un type, jamais sa signification observable.
Lorsqu'une capacité n'existe pas sur une cible, le compilateur ou le resolver doit produire une erreur explicite plutôt que modifier silencieusement la sémantique.
## 2.5 Encodage lexical et ASCII du code — V1 REQUIS — FIGÉ
Les fichiers source Saselang sont encodés en UTF-8.
Le code lexicalement significatif reste ASCII :
```text
keywords
identifiers
numeric literals
operators
punctuation
syntactic whitespace
namespace syntax
```
Unicode est autorisé dans les zones dont le contenu textuel le justifie :
```text
String literals
char literals
ordinary comments
Saseldoc comments
```
Un identifiant accentué ou un whitespace Unicode non ASCII placé dans le code est une erreur. Saselang n'accepte notamment pas les espaces insécables, espaces fines ou caractères Unicode ressemblant visuellement à une ponctuation ASCII comme substituts syntaxiques.
Le BOM UTF-8 est accepté uniquement au tout début du fichier et ignoré. Il n'est jamais requis. Le formatter officiel peut produire des fichiers sans BOM comme représentation canonique.
Les fins de ligne physiques `LF`, `CRLF` et `CR` sont acceptées et normalisées lexicalement en une même notion de fin de ligne.
Le whitespace syntaxique autorisé est limité à :
```text
U+0020 SPACE
U+0009 TAB
U+000A LF
U+000D CR
```
Indentation et retours à la ligne n'ont aucune signification grammaticale. Un programme Saselang valide peut, hors contenu textuel significatif, être écrit sur une seule ligne.
Un caractère NUL brut dans le fichier source est interdit hors représentation valide dans un littéral.
## 2.6 Identifiants — V1 REQUIS — FIGÉ
Les identifiants utilisateur sont ASCII, sensibles à la casse et suivent la forme générale :
```regex
[A-Za-z_][A-Za-z0-9_]*
```
Saselang n'impose pas `camelCase`, `PascalCase`, `snake_case` ou `UPPER_SNAKE_CASE` aux fonctions, méthodes, variables, constantes, paramètres ou membres. Les outils officiels, formatter compris, ne doivent pas renommer automatiquement les identifiants pour imposer un style.
La seule contrainte de casse structurelle est celle des types nominaux non primitifs : leur premier caractère doit être une lettre ASCII majuscule.
Les identifiants commençant par deux underscores sont réservés au compilateur, au runtime et au tooling Saselang :
```text
_value // utilisateur autorisé
__value // réservé interne
```
Les raw/escaped identifiers destinés à contourner un mot réservé sont interdits : pas de backticks ni de forme équivalente à `r#identifier`.
## 2.7 Ponctuation et tokenisation — V1 REQUIS — FIGÉ EN PRINCIPE
La ponctuation ASCII utilisée ou réservée est traitée explicitement par le lexer. Les caractères Unicode ressemblants ne sont jamais des alias.
Les principaux rôles V1 sont notamment :
```text
( ) grouping, calls, control headers, parameters
[ ] indexing et constructions définies par leur grammaire
{ } blocks et constructions à accolades
; fin d'un statement ou d'une déclaration sans corps
, séparation de deux éléments ; séparateur de listes init/update dans for
. qualification de namespace
:: qualification de membre/symbole
=> séparateur grammatical pattern -> bloc dans match
= assignment
+ - * / % arithmetic
& | ^ ~ bitwise/logical selon type ; | sépare aussi les alternatives d'un pattern
! logical negation / !=
< > comparaison, shifts et syntaxe générique selon contexte
.. famille de délimiteurs de Range, avec >.., ..< et >..<
' char delimiter
" String delimiter
_ identifiant / séparateur numérique / wildcard de pattern selon contexte
```
Les caractères suivants restent disponibles/réservés lorsqu'ils n'ont pas déjà un rôle lexical précis :
```text
# raw-string delimiter et shebang autorisé seulement selon sa règle dédiée
@ réservé hors commentaires/Saseldoc
$ réservé, notamment pendant la finalisation de l'interpolation
? réservé sans sémantique V1 encore attribuée
` réservé/interdit à l'utilisateur
\ uniquement selon les règles d'escape des littéraux
```
Le `?` est réservé sans recevoir de sémantique avant la fermeture du groupe `Option`/`Nullable`/propagation d'erreur.
Le lexer applique la règle du plus long token valide (`longest match`) pour les séquences définies telles que `>>=`, `<<=`, `::`, `!=`, `&&`, etc. Cette règle ne crée jamais un opérateur inexistant.
Les commentaires et les littéraux sont reconnus avant d'interpréter leur contenu comme ponctuation ou opérateurs.
Dans un contexte générique, le parser peut interpréter une séquence lexicale telle que `>>` comme deux fermetures `>` lorsque la grammaire l'exige, afin d'autoriser par exemple :
```text
Map<String,List<int32>>
```
sans espace artificiel.
## 2.8 Diagnostics de style et lints — V1 REQUIS — FIGÉ EN PRINCIPE
Le compilateur Saselang distingue les erreurs de correction/sémantique des observations de qualité de code.
Par défaut, une construction valide n'est pas signalée simplement parce qu'une valeur, une variable locale, un paramètre ou un item privé n'est jamais réutilisé. Par exemple :
```text
{
int32 myvar = 42;
}
```
est valide sans warning obligatoire, même si `myvar` disparaît à la fin du bloc sans avoir été lu.
Les diagnostics tels que `unused local`, `unused parameter`, `unused private item`, `dead private declaration` ou équivalents relèvent d'un système de lint configurable et désactivable. Ils peuvent être explicitement activés par l'utilisateur, le projet ou un outil d'analyse, mais ne font pas partie du comportement diagnostic par défaut du langage.
Le formatter ne doit pas devenir un linter de nommage ni modifier la sémantique du programme.
---

53
chapters/003-architecture-de-compilation.md Normal file
View File

@@ -0,0 +1,53 @@
# 3. Architecture de compilation
## 3.1 Pipeline — V1 REQUIS — FIGÉ
```text
Source
-> lexer
-> parser
-> AST
-> modèle sémantique
-> HIR
-> Sase IR
-> backend / interpréteur
```
L'AST ne doit pas être couplé directement à LLVM.
Le Sase IR est la frontière principale entre la sémantique Saselang et les backends.
## 3.2 Interpréteur — V1 REQUIS — À FINALISER
La V1 doit inclure un interpréteur Saselang.
La représentation exacte interprétée reste à décider :
```text
HIR
Sase IR
bytecode dérivé de Sase IR
```
Le choix ne doit pas créer une seconde sémantique du langage.
## 3.3 Backend LLVM — V1 REQUIS — FIGÉ
LLVM est le premier backend compilé.
Il doit pouvoir produire selon la cible et la configuration :
```text
machine code
object file
native executable
static library
dynamic/shared library
textual assembly
```
L'assembleur textuel est un artefact de backend, pas une syntaxe du langage Saselang.
NASM est le premier dialecte explicite à étudier pour x86/x86_64. Il ne doit pas être imposé aux architectures où il n'est pas pertinent.
---

95
chapters/004-couches-de-lecosysteme-v1.md Normal file
View File

@@ -0,0 +1,95 @@
# 4. Couches de l'écosystème V1
## 4.1 Saselang Language — V1 REQUIS — FIGÉ
Le langage comprend notamment :
```text
grammaire
types primitifs
types nominaux
fonctions/méthodes
classes
structs
interfaces
enums
unions
tuples
generics
contrôle de flux
erreurs/exceptions
opérateurs
unsafe
scope
visibilité
imports
compilation conditionnelle structurelle
```
## 4.2 Saselang Core — V1 REQUIS — À FINALISER
Le Core est minimal et contient les types fondamentaux non primitifs nécessaires au langage.
Les types compiler-known doivent rester rares.
Candidats actuellement nécessaires ou fortement retenus :
```text
Object
String
Result<T>
Result<T,E>
Error
ResultError
Exception
Option<T>
Nullable<T>
Range<T>
RangeIterable<T>
RangeStep<T,Step>
RangeReverse<T>
RangeReverseStep<T,Step>
RangeProgression<T,Step>
Ordering
Op...
Iterable<T>
Iterator<T>
Array<T>
StaticArray<T,N>
TypeInfo
ExitCode
```
Le fait d'être compiler-known ne transforme pas un type en primitive.
Les primitives peuvent exposer des membres standard définis par le Core sans devenir des classes. Les conversions numériques standard constituent un exemple important : leur surface API appartient au Core, tandis que le compilateur ne connaît que les règles de typage, les contrats d'intrinsics et les opérations Sase IR nécessaires à leur validation et à leur lowering.
Une capacité Core peut être conditionnée par un target lorsqu'elle ne peut raisonnablement pas être garantie partout. Une optimisation matérielle ne suffit pas à rendre une capacité conditionnelle si une implémentation logicielle conforme est raisonnable. L'absence d'une capacité réellement requise doit être diagnostiquée à la compilation pour le target choisi.
## 4.3 Saselang SDK — V1 REQUIS — À FINALISER
Le SDK fournit les fonctionnalités de bibliothèque qui ne justifient pas une sémantique spéciale du compilateur :
```text
collections
encodages explicites
regex
filesystem
networking
process
concurrence
math
algèbre
FFI helpers
plateforme
```
Le découpage exact Core/SDK doit être finalisé avant gel de l'API V1.
## 4.4 Runtime réduit — V1 REQUIS — FIGÉ EN PRINCIPE
Une application native simple ne doit pas être forcée d'embarquer un runtime monolithique.
Les services runtime doivent être ajoutés par capacités réelles.
---

218
chapters/005-types-primitifs.md Normal file
View File

@@ -0,0 +1,218 @@
# 5. Types primitifs
## 5.1 Liste V1 — V1 REQUIS — FIGÉ
```text
int8 int16 int32 int64 int128 int256
uint8 uint16 uint32 uint64 uint128 uint256
float16 float32 float64 float128
bool
char
```
`Void` est un type/symbole spécial du Core/langage et ne doit pas être confondu avec un tuple vide.
### 5.1.1 Statut de `Void` — V1 REQUIS — FIGÉ
`Void` représente explicitement l'absence de valeur utile ou de payload de succès. Il n'est pas un type de stockage général.
Usages autorisés en V1 :
```text
-> Void
Result<Void,E>
Result<Void>
```
Exemple :
```text
func save() -> Result<Void> {
...
return Result::Ok(Void);
}
```
Les usages suivants sont interdits :
```text
Void value;
field Void
Option<Void>
Nullable<Void>
Array<Void>
Range<Void>
```
`return Void;` reste obligatoire dans une callable à retour direct `Void`. `Result<Void,E>` exprime un succès sans payload utile tout en conservant un canal d'erreur explicite.
## 5.2 Largeur exacte — V1 REQUIS — FIGÉ
La largeur d'un type primitif ne dépend jamais de la cible.
Il n'existe pas de `int`, `uint` ou `usize` dont la largeur change suivant la plateforme.
Si un target ne sait pas représenter un type demandé, il produit une erreur de compilation.
## 5.3 Primitives et Object — V1 REQUIS — FIGÉ
Les primitives :
- ne sont pas des classes ;
- n'héritent pas de `Object` ;
- ne sont pas définissables par l'utilisateur ;
- peuvent exposer des opérations compiler/Core-known avec syntaxe membre lorsque cela simplifie l'API.
Exemple :
```text
value::toString()
float16::fromInt32(value)
```
## 5.4 Représentation des entiers — V1 REQUIS — FIGÉ
Les entiers signés utilisent une sémantique binaire définie en complément à deux pour les opérations bitwise.
## 5.5 Arithmétique des entiers — V1 REQUIS — FIGÉ
Overflow arithmétique : checked et déterministe en debug comme en release.
```text
overflow statiquement prouvable -> erreur de compilation
overflow dynamique -> faute runtime déterministe
```
Des méthodes explicites pourront fournir :
```text
wrapping
saturating
checked
```
Division entière : troncature vers zéro.
Division par zéro :
```text
statique -> erreur compilation
dynamique -> faute runtime
```
`MIN / -1` est un overflow.
Le reste `%` respecte :
```text
a == (a / b) * b + (a % b)
```
et son signe suit le dividende.
Le modulo euclidien sera une opération explicite du Core/SDK.
## 5.6 Floats — V1 REQUIS — À FINALISER
La sémantique flottante suit IEEE pour les représentations et opérations applicables. Les littéraux sont arrondis vers le type flottant cible selon les règles IEEE normales ; Saselang n'exige pas qu'un littéral décimal soit représentable exactement.
Le tableau exact des cas particuliers, conversions, NaN, infinities, division par zéro et comportement de `%` flottant doit être normatif avant implémentation finale.
## 5.7 Littéraux numériques — V1 REQUIS — FIGÉ EN PRINCIPE
Entiers :
```text
42 decimal
0b101010 binary
0o52 octal
0x2a hexadecimal
```
Les préfixes de base sont canoniquement en minuscules : `0b`, `0o`, `0x`.
Les séparateurs `_` sont autorisés uniquement entre deux chiffres valides appartenant à une même composante numérique :
```text
1_000_000
0b1010_1100
0xffff_ffff
1.234_567
1.0e1_000
```
Sont notamment invalides : `_1`, `1_`, `1__0`, `0x_ff`, `1_.0`, `1._0`, `1e_10`.
Un littéral flottant décimal contient un point décimal et/ou un exposant `e`/`E` :
```text
1.0
0.5
42.25
1e6
1.5e-3
```
Les formes `1.` et `.5` ne sont pas canoniques et sont interdites ; écrire `1.0` et `0.5`.
Les suffixes courts sont réservés et retenus :
```text
i8 i16 i32 i64 i128 i256
u8 u16 u32 u64 u128 u256
f16 f32 f64 f128
```
Exemples :
```text
42i32
42u64
1.5f16
```
Un littéral non suffixé est typé par le contexte lorsqu'un type attendu existe et que sa valeur est représentable. Sans contexte, le type par défaut est `int32` pour un entier et `float64` pour un flottant. Cette contextualisation des littéraux ne constitue pas une inférence générale du type des variables et n'introduit aucune promotion implicite entre valeurs déjà typées.
Le signe négatif n'appartient pas au token numérique : `-42` est l'opérateur unaire `-` appliqué au littéral `42`. L'analyse constante doit néanmoins permettre les minimums signés exacts tels que `int8 x = -128;` en validant la valeur finale contextualisée.
Un entier littéral hors plage de son type contextualisé ou suffixé produit une erreur de compilation. Le frontend peut représenter temporairement les littéraux entiers avec une précision arbitraire pendant l'analyse avant validation du type final.
Un littéral flottant est arrondi selon IEEE vers le type cible. Un overflow du littéral lui-même hors plage du type cible est une erreur de compilation plutôt qu'une conversion silencieuse en infinity.
NaN et les infinities ne sont pas des pseudo-littéraux lexicaux ; ils sont exposés par le Core selon une API à finaliser.
### 5.7.1 Flottants hexadécimaux — V1 RÉSERVÉ / PROBABLE V2
La syntaxe des flottants hexadécimaux est réservée dès V1 afin de préserver les usages bas niveau futurs, même si l'implémentation complète peut être différée :
```text
0x1.0p0
0x1.8p1
0x1.ffp10
0x1.0p-20
```
`p` introduit l'exposant binaire. Les suffixes flottants courts pourront s'appliquer à cette forme, par exemple `0x1.8p1f32`.
La forme canonique utilise `0x` et `p` en minuscules. Le séparateur `_` suit la même règle générale d'utilisation entre chiffres valides.
### 5.7.2 Conversion explicite et bitcast — V1 REQUIS — DIRECTION FIGÉE
Les suffixes de littéral et les conversions explicites sont deux mécanismes distincts et complémentaires :
```text
1f16
1::toFloat16()
```
La première forme donne directement un type au littéral ; la seconde exprime une conversion numérique explicite. Les primitives peuvent exposer des opérations compiler/Core-known telles que `toFloat16()`.
Une conversion numérique reste distincte de :
```text
bitcast<float16>(value)
```
qui réinterprète les bits selon les règles de `bitcast`. Les règles de plage et d'échec des conversions sont différées au groupe casts/conversions.
---

52
chapters/006-types-variables-constantes-et-scopes.md Normal file
View File

@@ -0,0 +1,52 @@
# 6. Types, variables, constantes et scopes
## 6.1 Typage explicite — V1 REQUIS — FIGÉ
Une variable possède un type explicite.
Pas de `var`, `let` ou `auto` utilisé comme inférence générale de l'identité de type d'une variable.
Les littéraux suivent les règles de contextual typing figées à la section 5.7 ; cela ne constitue pas une inférence générale du type des variables.
## 6.2 Definite assignment — V1 REQUIS — FIGÉ
Une variable peut être déclarée sans valeur initiale seulement si le compilateur prouve qu'elle est assignée avant toute lecture.
Une constante peut être assignée exactement une fois sur plusieurs chemins si le compilateur prouve l'unicité et la complétude de l'assignation.
## 6.3 Shadowing — V1 REQUIS — FIGÉ
Le shadowing est interdit tant qu'une déclaration précédente de même nom est visible.
Réutilisation autorisée après fin complète du scope précédent :
```text
{
int32 value = 1;
}
{
int32 value = 2;
}
```
Deux branches disjointes peuvent réutiliser le même nom.
## 6.4 Blocs anonymes — V1 REQUIS — FIGÉ
Un bloc exécutable anonyme peut créer un scope à l'intérieur d'une fonction, méthode, `clsmethod`, `construct` ou `destruct`.
Les blocs exécutables anonymes top-level sont interdits dans les sources ordinaires.
## 6.5 Ordre d'évaluation — V1 REQUIS — FIGÉ
Les opérandes et arguments sont évalués de gauche à droite et une seule fois.
Exemple :
```text
foo(a(), b(), c())
```
évalue `a()`, puis `b()`, puis `c()`.
---

23
chapters/007-types-nominaux-et-fichiers-saseltype.md Normal file
View File

@@ -0,0 +1,23 @@
# 7. Types nominaux et fichiers `.saseltype`
## 7.1 Nommage — V1 REQUIS — FIGÉ
Les types nominaux non primitifs commencent obligatoirement par une lettre ASCII majuscule. Aucune convention `UpperCamelCase`, `PascalCase` ou autre n'est imposée au-delà de cette première lettre.
## 7.2 Types nominaux V1 — V1 REQUIS — FIGÉ
Un fichier `.saseltype` peut définir exactement un des types suivants :
```text
class
struct
interface
enum
union
```
Le nom du fichier doit correspondre au nom du type.
Le fichier ne contient pas d'autres types top-level ni de fonctions auxiliaires top-level.
---

78
chapters/008-classes-et-object.md Normal file
View File

@@ -0,0 +1,78 @@
# 8. Classes et `Object`
## 8.1 Héritage de base — V1 REQUIS — FIGÉ
Toutes les classes héritent implicitement de `Object`, sauf `Object` lui-même.
Les primitives, structs, enums, tuples et unions n'héritent pas artificiellement de `Object`.
## 8.2 Héritage de classes — V1 REQUIS — FIGÉ
Héritage de classe unique uniquement.
Une classe concrète doit être explicitement :
```text
open
ou
final
```
Une classe abstraite est :
```text
abstract
```
`abstract`, `open` et `final` sont mutuellement exclusifs au niveau classe.
## 8.3 Receivers — V1 REQUIS — FIGÉ
```text
this instance courante
super instance de la classe parente immédiate
cls classe courante dans une clsmethod
parent classe parente immédiate dans une clsmethod
```
Pas de :
```text
super::super
parent::parent
```
## 8.4 Accès membre — V1 REQUIS — FIGÉ
Les membres sont accédés explicitement avec `::` :
```text
this::field
token::kind()
Type::member
super::method()
```
`.` qualifie les namespaces/modules/types ; `::` accède à un symbole contenu.
Ils relèvent de la grammaire et ne sont pas surchargeables.
## 8.5 Identité d'instance — V1 REQUIS — FIGÉ
`Object` fournit une opération intrinsèque non overridable :
```text
Object::sameInstance(Object other) -> bool
```
Elle teste l'identité d'instance, c'est-à-dire si deux références désignent exactement le même objet.
Elle n'est pas équivalente à `==`.
Exemple : deux objets différents peuvent être logiquement égaux mais ne pas être la même instance.
`Object` n'implémente pas automatiquement `OpEqual` ni `OpPartialEqual`.
Les classes ne reçoivent donc aucune égalité de valeur automatique.
---

26
chapters/009-structs.md Normal file
View File

@@ -0,0 +1,26 @@
# 9. Structs
## 9.1 Nature — V1 REQUIS — FIGÉ
Une `struct` est un type nominal de valeur :
- pas d'héritage de struct ;
- peut implémenter des interfaces ;
- pas d'identité d'instance `Object` ;
- pas d'égalité/comparaison automatique générale ;
- construction/destruction selon les règles du modèle mémoire V1.
## 9.2 Visibilité — V1 REQUIS — FIGÉ
Membres de struct :
```text
private
module
package
public
```
Pas de `protected`, car il n'existe pas d'héritage de struct.
---

23
chapters/010-enums-algebriques.md Normal file
View File

@@ -0,0 +1,23 @@
# 10. Enums algébriques
## 10.1 Nature — V1 REQUIS — FIGÉ
Les enums Saselang sont fermés et peuvent porter des données.
Ils doivent permettre un `match` exhaustif.
## 10.2 Héritage — V1 REQUIS — FIGÉ
Pas d'héritage d'enum.
Un enum peut implémenter des interfaces.
Les variantes suivent la visibilité de l'enum.
## 10.3 Égalité/comparaison — V1 REQUIS — FIGÉ EN PRINCIPE
Pas de génération générale automatique d'`OpEqual` ou `OpCompare` pour tous les enums nominaux.
Des comportements intrinsèques peuvent être définis explicitement pour certains enums Core.
---

54
chapters/011-tuples.md Normal file
View File

@@ -0,0 +1,54 @@
# 11. Tuples
## 11.1 Nature — V1 REQUIS — FIGÉ
Un tuple est un type structurel anonyme, hétérogène, d'arité fixe.
Il n'a pas de `.saseltype`.
```text
(int32, String)
```
`(T)` est un groupement, pas un tuple à un élément.
Il n'existe pas de tuple `()` ; `Void` exprime l'absence de valeur.
Arity minimale : 2.
## 11.2 Champs — V1 REQUIS — FIGÉ
Les tuples ne possèdent pas de noms de membres persistants.
Si des champs nommés stables sont nécessaires, utiliser une `struct`.
La déstructuration peut nommer des variables locales :
```text
(int32 id, String name) = value;
```
Ces noms ne changent pas le type du tuple.
## 11.3 Indexation — V1 REQUIS — FIGÉ
Accès positionnel :
```text
tuple[0]
tuple[1]
```
L'index doit être une constante connue à la compilation puisque le type de retour peut varier suivant la position.
Le tuple n'implémente donc pas un `OpIndex<uint64,T>` homogène ordinaire.
## 11.4 Égalité/comparaison intrinsèque — V1 REQUIS — FIGÉ
Si tous les éléments permettent l'égalité pertinente, le tuple peut être comparé composant par composant.
Si tous les éléments sont comparables, l'ordre du tuple est lexicographique.
Si un composant comparé retourne `Ordering::Unordered`, le tuple est `Unordered`.
---

54
chapters/012-unions.md Normal file
View File

@@ -0,0 +1,54 @@
# 12. Unions
## 12.1 `union` sûre — V1 REQUIS — FIGÉ
Une `union` sûre est un overlay mémoire nominal limité à des représentations binaires compatibles dont chaque motif de bits est acceptable selon les règles définies.
V1 vise initialement les familles primitives numériques :
```text
int*
uint*
float*
```
Tous les champs recouvrent la même zone mémoire.
La taille correspond au membre le plus grand, avec alignement/padding requis.
Lire une autre vue est une réinterprétation de bits définie par Saselang.
Pas de tag, pas de `match` exhaustif automatique.
## 12.2 `unsafe union` — V1 REQUIS — FIGÉ EN PRINCIPE
```text
public unsafe union RawValue
```
permet des types mémoire triviaux dont certaines représentations peuvent être invalides :
```text
bool
char
raw pointers
fixed compatible arrays
FFI-safe trivial structs
compatible unsafe unions
```
Les types avec ownership/lifecycle non trivial tels que `String`, fichiers, classes ou collections dynamiques ne doivent pas être stockables arbitrairement dans une raw union V1.
Les règles exactes de validité et d'accès sont liées au modèle mémoire V1.
## 12.3 ABI C — V1 REQUIS — À FINALISER
Le linkage/ABI est orthogonal à `unsafe` :
```text
public unsafe extern "C" union NativeValue
```
La syntaxe canonique des unions FFI est conservée ; la liste exacte des layouts garantis doit être finalisée avec la FFI.
---

87
chapters/013-interfaces.md Normal file
View File

@@ -0,0 +1,87 @@
# 13. Interfaces
## 13.1 Nature — V1 REQUIS — FIGÉ
Saselang utilise des interfaces et ne prévoit pas un concept séparé de `trait` en V1.
Une interface :
- peut hériter de plusieurs interfaces ;
- ne possède pas d'état d'instance propre ;
- ne possède pas de `construct`/`destruct` d'instance ;
- peut fournir des méthodes par défaut ;
- peut définir des constantes associées de contrat.
## 13.2 Méthodes de contrat et defaults — V1 REQUIS — FIGÉ
Sans corps : contrat abstrait implicite.
Avec corps : implémentation par défaut.
Pas besoin de `abstract` ou `open` sur une méthode d'interface.
## 13.3 Signature — V1 REQUIS — FIGÉ
La signature de surcharge d'une méthode contient uniquement :
```text
nom
+ ordre des paramètres
+ type de chaque paramètre
```
Le type de retour ne fait pas partie de la signature.
## 13.4 Contrat — V1 REQUIS — FIGÉ EN PRINCIPE
Pour la compatibilité d'héritage, le contrat comprend au minimum :
```text
type de retour
visibilité
fallibilité / Result
throws
contraintes génériques pertinentes
modificateurs contractuels pertinents
```
Les futurs pré/post-contrats formels, s'ils existent, devront également participer à cette notion.
## 13.5 Conflits d'héritage multiple — V1 REQUIS — FIGÉ
Lorsque deux chemins héritent de la même signature :
1. si les contrats diffèrent -> erreur de compilation ;
2. si les contrats sont compatibles et aucun default distinct n'existe -> fusion du contrat ;
3. si un seul default distinct existe -> ce default est hérité ;
4. si deux defaults distincts existent -> override explicite obligatoire ;
5. si les deux chemins héritent exactement du même default depuis un ancêtre commun sans le redéfinir -> pas de faux conflit.
Il n'existe aucune priorité implicite « premier parent gagne » ou « dernier parent gagne ».
## 13.6 Visibilité des contrats — V1 REQUIS — FIGÉ
Les contrats d'interface peuvent être :
```text
module
package
public
```
Pas de `private` ni `protected` pour un contrat exposé par interface.
## 13.7 Constantes associées — V1 REQUIS — À FINALISER
Direction retenue :
```text
public interface Ring<T> {
public const T Zero;
public const T One;
}
```
Une interface pourra probablement fournir une valeur par défaut à une constante associée, mais syntaxe, résolution des conflits et règles de spécialisation doivent encore être figées.
---

34
chapters/014-generics.md Normal file
View File

@@ -0,0 +1,34 @@
# 14. Generics
## 14.1 Disponibilité — V1 REQUIS — FIGÉ
Les generics font partie de V1.
Exemples :
```text
Array<T>
Result<T,E>
OpAdd<Lhs,Rhs,Out>
```
## 14.2 Points restant à fermer — V1 REQUIS — À FINALISER
Doivent encore être spécifiés précisément :
```text
syntaxe des contraintes
variance ou absence de variance
contraintes multiples
specialization éventuelle
monomorphisation vs représentation partagée
contraintes sur types primitifs
const generics pour StaticArray<T,N>
generic methods
inférence éventuelle des arguments génériques à l'appel
wildcards/existentials éventuels
```
Le type de retour ne doit pas devenir un moyen de résoudre une surcharge ambiguë.
---

69
chapters/015-fonctions-methodes-et-clsmethod.md Normal file
View File

@@ -0,0 +1,69 @@
# 15. Fonctions, méthodes et `clsmethod`
## 15.1 Catégories — V1 REQUIS — FIGÉ
```text
func fonction libre
method méthode d'instance
clsmethod méthode de classe
operator implémentation d'un contrat opérateur
```
## 15.2 Retours directs et `Result` — V1 REQUIS — FIGÉ
L'ancienne règle « toute fonction/méthode retourne `Result` » est supprimée.
Règle V1 :
```text
opération infaillible
-> retourne directement T
opération pouvant produire une erreur récupérable
-> retourne Result<T>
ou Result<T,E>
```
Exemples infaillibles :
```text
method length() -> uint64
method containsKey(K key) -> bool
Object::sameInstance(Object other) -> bool
func min(int32 a, int32 b) -> int32
```
Exemples faillibles :
```text
func readFile(String path) -> Result<String, IoError>
method parse(String input) -> Result<Value, ParseError>
```
## 15.3 Retour explicite — V1 REQUIS — FIGÉ
Pas de retour implicite de dernière expression.
```text
return value;
return Result::Ok(value);
return Result::Ok(Void);
```
`return` quitte la fonction/méthode.
## 15.4 Surcharge — V1 REQUIS — FIGÉ
Surcharge autorisée pour fonctions et méthodes.
La signature ne contient pas le type de retour.
Il ne peut donc pas exister deux overloads distingués uniquement par leur retour.
## 15.5 Résolution de surcharge — V1 REQUIS — À FINALISER
Les règles exactes de préférence entre exact match, conversions explicites/contextuelles, generics et variadiques doivent être figées.
Objectif : aucune résolution basée sur le type de retour et aucune conversion implicite ambiguë.
---

86
chapters/016-dispatch-override-et-modificateurs.md Normal file
View File

@@ -0,0 +1,86 @@
# 16. Dispatch, override et modificateurs
## 16.1 Ordre canonique — V1 REQUIS — FIGÉ
Ordre des modificateurs :
```text
visibility
-> safety
-> linkage / ABI
-> type / dispatch modifiers
-> override
-> declaration kind
```
Puis :
```text
Name<...>
-> extends ...
-> implements ...
```
`extends` et `implements` sont des clauses après le nom, pas des modificateurs.
Exemples :
```text
public final class User
public open class Service
public abstract class Base
public unsafe extern "C" union NativeValue
protected open method calculate(...)
protected override method calculate(...)
protected final override method calculate(...)
```
Les ordres alternatifs sont des erreurs syntaxiques même s'ils seraient théoriquement compréhensibles.
## 16.2 Méthodes overridables — V1 REQUIS — FIGÉ
Une méthode nouvellement déclarée n'est pas overridable par défaut.
Elle doit être explicitement :
```text
open method
```
ou :
```text
abstract method
```
Un descendant utilise :
```text
override method
```
Pour fermer ensuite la chaîne :
```text
final override method
```
`final method` sur une nouvelle méthode n'apporte rien et n'est pas nécessaire : l'absence de `open` suffit.
Même modèle pour `clsmethod` si elle participe au dispatch de classe.
## 16.3 Visibilité d'override — V1 REQUIS — FIGÉ
Un override conserve exactement la visibilité du contrat hérité.
Pas d'élargissement ni de réduction implicite.
Une exposition plus large nécessite un wrapper explicite.
## 16.4 `protected` — V1 REQUIS — FIGÉ EN PRINCIPE
`protected` existe uniquement dans le modèle d'héritage de classe et signifie « accessible depuis les classes dérivées » en plus de la classe déclaratrice.
Les détails d'accès via une autre instance d'une classe dérivée doivent être figés dans les règles finales de résolution membre.
---

86
chapters/017-construction-et-destruction.md Normal file
View File

@@ -0,0 +1,86 @@
# 17. Construction et destruction
## 17.1 Constructeur unique — V1 REQUIS — FIGÉ
Une classe ou struct possède au maximum un `construct` effectif explicite ou synthétique.
Pas de surcharge de constructeur.
## 17.2 Visibilité de `construct` — V1 REQUIS — FIGÉ
Classe :
```text
private
protected
module
package
public
```
Struct :
```text
private
module
package
public
```
`unsafe construct` est autorisé si l'appelant doit garantir des invariants que le compilateur ne peut pas vérifier.
## 17.3 Construction dérivée — V1 REQUIS — FIGÉ
Chaque classe possède son propre constructeur effectif ; les constructeurs ne sont pas hérités comme des méthodes.
Le compilateur peut synthétiser un constructeur à partir :
- du constructeur effectif du parent immédiat ;
- des nouveaux champs qui nécessitent une initialisation.
Chaîne :
```text
C -> B -> A
```
Jamais `C -> A` directement.
## 17.4 `super::construct(...)` — V1 REQUIS — FIGÉ
Il doit être exécuté exactement une fois sur chaque chemin de construction valide avant toute utilisation de l'état parent via `this`/`super`.
Il n'a pas besoin d'être textuellement la première instruction : des calculs locaux indépendants peuvent le précéder.
Le compilateur doit prouver la definite construction.
Avant construction du parent, sont notamment interdits :
```text
this::field
this::method()
super::method()
escape/capture/pass de this
```
## 17.5 Destructeur — V1 REQUIS — FIGÉ EN PRINCIPE
Au maximum un `destruct` effectif.
Le destructeur est un hook de lifecycle automatiquement invoqué.
Il n'est pas appelable directement par le programmeur et ne possède donc pas de visibilité utilisateur normale.
```text
destruct() {
...
}
```
S'il doit effectuer des opérations unsafe, il utilise un bloc `unsafe` interne.
## 17.6 Fallibilité de `construct`/`destruct` — V1 REQUIS — À FINALISER
Le lien exact avec `Result`, exceptions, construction partielle et cleanup doit être fermé avec le modèle mémoire et les exceptions.
---

355
chapters/018-result-erreurs-et-exceptions.md Normal file
View File

@@ -0,0 +1,355 @@
# 18. `Result`, erreurs et exceptions
## 18.1 Hiérarchie Core — V1 REQUIS — FIGÉ
La hiérarchie d'erreurs V1 est :
```text
Object
└── Error
├── ResultError
└── Exception
```
Les trois classes racines sont abstraites et ne sont donc jamais instanciées directement.
`Error` est la racine abstraite commune des erreurs Saselang. Elle ne détermine pas à elle seule le mécanisme de propagation.
`ResultError` représente exclusivement la famille des erreurs transportables par `Result<T,E>`.
`Exception` représente exclusivement la famille des erreurs propagées par `throw` / `throws` / `try` / `catch` / `finally`.
`ResultError` et `Exception` sont des branches sœurs. Une classe utilisateur destinée à un `Result` hérite directement ou indirectement de `ResultError`. Une exception utilisateur hérite directement ou indirectement de `Exception`.
Exemple :
```text
public final class ParseError extends ResultError {
}
public final class FileNotFoundException extends Exception {
}
```
L'interface `Throwable` ne fait pas partie de Saselang V1. Elle pourra être réintroduite ultérieurement si un besoin réel apparaît sans modifier la règle fondamentale : `Result` transporte des `ResultError`, tandis que `throw` transporte des `Exception`.
## 18.2 Informations communes de `Error` — V1 REQUIS — FIGÉ EN PRINCIPE
`Error` reste volontairement généraliste et minimal. Il porte conceptuellement :
```text
message: String
cause: Option<Error>
i18nMessage: Option<I18nMessage>
```
Rôles :
```text
message
message humain canonique / fallback
cause
erreur causale purement informative
peut contenir un ResultError ou une Exception
n'est pas automatiquement propagée
i18nMessage
clé et paramètres de localisation
ne contient pas un tableau de traductions
```
`cause` est de type `Option<Error>` et non `Nullable<Error>` : l'absence de cause est une absence sémantique. Une cause de type statique `Error` ne peut pas être passée directement à `throw`; il faut d'abord prouver par `is` qu'elle est une `Exception`, ou l'encapsuler explicitement dans une nouvelle exception.
`message`, `cause` et `i18nMessage` sont initialisés lors de la construction et ne sont pas publiquement mutables.
`Error` ne porte pas de propriétés universelles supplémentaires telles que timestamp, thread id, process id, host, severity ou code plateforme. Ces informations appartiennent aux sous-classes, SDKs ou couches de logging/diagnostic lorsqu'elles sont pertinentes.
Le type exact `I18nMessage`, sa clé et la représentation de ses paramètres seront finalisés avec Core/SDK et le système de formatting/i18n.
## 18.3 `ResultError` et code machine-readable — V1 REQUIS — FIGÉ EN PRINCIPE
`ResultError` ajoute conceptuellement un code stable, non localisé et exploitable par le programme :
```text
code: ResultErrorCode
```
Le rôle de `ResultErrorCode` est distinct de `message` :
```text
code -> stable, machine-readable, non localisé
message -> humain, canonique / fallback
i18nMessage -> localisation externe
```
La représentation exacte de `ResultErrorCode` sera finalisée avec Core/SDK. `Exception` n'a pas de code obligatoire.
## 18.4 `Exception` et stack trace — V1 REQUIS — FIGÉ EN PRINCIPE
`Exception` reste généraliste. Elle peut recevoir des informations de stack trace liées à sa propagation.
La création d'un objet `Exception` ne doit pas obligatoirement capturer immédiatement une stack trace. Le contexte de propagation peut être attaché ou capturé lors de :
```text
throw exception;
```
La représentation exacte (`StackTrace`, `StackFrame`, capture lazy ou autre optimisation) relève de Core/runtime. Cette information reste diagnostique et n'intervient pas dans la sélection des `catch`.
`Error` et `ResultError` n'ont pas de stack trace automatique obligatoire.
## 18.5 `Result<T,E>` — V1 REQUIS — FIGÉ
`Result<T,E>` est un type Core algébrique avec exactement deux variantes conceptuelles :
```text
Result::Ok(T)
Result::Err(E)
```
Le paramètre d'erreur est contraint :
```text
E doit être ResultError ou un descendant de ResultError
```
Sont valides :
```text
Result<Data,ResultError>
Result<Data,ParseError>
Result<Void,ResultError>
```
Sont invalides :
```text
Result<Data,Error>
Result<Data,Exception>
Result<Data,FileNotFoundException>
```
La forme courte :
```text
Result<T>
```
est équivalente à :
```text
Result<T,ResultError>
```
`Result<Void,E>` et `Result<Void>` sont autorisés pour représenter un succès sans payload utile. `Option<Void>` reste interdit.
Il n'existe aucune conversion implicite de `T` vers `Result<T,E>` ni de `E` vers `Result<T,E>` :
```text
return Result::Ok(value);
return Result::Err(error);
```
sont explicites.
`Result` suit les règles générales des enums algébriques. Son inspection et l'extraction sûre de ses payloads utilisent `match` avec bindings typés. V1 n'introduit ni `unwrap`, ni opérateur `?`, ni extraction implicite d'une variante.
Des helpers Core futurs tels que :
```text
result::expectOk(...)
result::expectErr(...)
```
peuvent être étudiés si un besoin réel apparaît. Ils resteraient une API de `Result`, pas une syntaxe du langage, et leur comportement d'échec devrait être explicitement spécifié.
## 18.6 Séparation `ResultError` / `Exception` — V1 REQUIS — FIGÉ
Aucune conversion automatique n'existe entre les deux branches :
```text
ResultError -> Exception
Exception -> ResultError
```
La traduction d'un mécanisme vers l'autre se fait par encapsulation explicite dans une nouvelle erreur de la branche cible, éventuellement en conservant l'erreur source dans `cause`.
Exemples conceptuels :
```text
throw ParseException(..., Option::Some(parseError));
```
ou :
```text
catch (FileNotFoundException error) {
return Result::Err(FileResultError(..., Option::Some(error)));
}
```
Un simple cast ne transforme pas un `ResultError` en `Exception` ni l'inverse.
## 18.7 `throws` — V1 REQUIS — FIGÉ
`throws` est interdit sur une `func` / `method` / `clsmethod` à retour direct. Il n'est permis que si le retour est `Result<T>` ou `Result<T,E>`.
```text
T + throws -> interdit
Result<T,E> -> valide sans throws
Result<T,E> + throws -> valide
```
Tout type déclaré dans `throws` doit être `Exception` ou un descendant de `Exception`.
Une callable doit déclarer toute famille d'exception susceptible d'atteindre sa frontière sans être gérée localement. Cette obligation est transitive : une exception déclarée par une callable appelée doit être soit capturée localement, soit couverte par le `throws` de l'appelant.
Un type déclaré dans `throws` couvre ses descendants. Une clause :
```text
throws IOException
```
peut donc couvrir `FileNotFoundException` si cette dernière hérite de `IOException`.
Une même clause `throws` ne doit pas contenir de types redondants lorsqu'un type déclaré couvre déjà entièrement un autre type de la liste.
## 18.8 `throws` dans les contrats, interfaces et overrides — V1 REQUIS — FIGÉ
`throws` ne fait pas partie de la signature d'overload. Il fait partie du contrat de la callable.
Un override ou une implémentation peut :
```text
supprimer entièrement des exceptions déclarées
restreindre une famille à une ou plusieurs sous-familles compatibles
gérer localement tout ou partie des exceptions du contrat parent
```
Il ne peut jamais ajouter une exception non couverte par le contrat parent ni élargir une famille déclarée.
La même règle s'applique aux contrats d'interface. Lorsque plusieurs interfaces portent la même signature, l'implémentation doit satisfaire simultanément tous leurs contrats `throws`. Une implémentation sans exception sortante est toujours compatible avec un contrat qui en autorise.
## 18.9 `throw` — V1 REQUIS — FIGÉ
`throw` ne peut lancer qu'une valeur dont le type statique est `Exception` ou un descendant de `Exception`.
```text
throw FileNotFoundException(...); // valide
throw ParseError(...); // erreur
throw Error(...); // erreur
```
Les racines abstraites `Error`, `ResultError` et `Exception` ne sont jamais instanciables directement.
La forme de repropagation reste explicite :
```text
catch (IOException error) {
throw error;
}
```
Il n'existe pas de forme spéciale `throw;` en V1.
## 18.10 `try` / `catch` / `finally` — V1 REQUIS — FIGÉ
Un `try` doit être suivi d'au moins un `catch`.
Sont interdits :
```text
try { ... }
try { ... } finally { ... }
finally { ... }
```
La forme générale est :
```text
try {
...
} catch (SpecificException error) {
...
} catch (ParentException error) {
...
} finally {
...
}
```
`finally` est facultatif et ne peut apparaître qu'après au moins un `catch`.
Chaque `catch` contient exactement un type explicite d'`Exception` ou descendant. Il n'existe pas de multi-catch `A | B` en V1 : des blocs `catch` distincts sont utilisés.
Les `catch` sont évalués dans l'ordre source. Le chevauchement par héritage est normal et utile : les cas spécifiques peuvent précéder un fallback de famille générale.
Un `catch` entièrement couvert par un `catch` précédent est une erreur de compilation, pas un simple warning.
Exemple valide :
```text
catch (FileNotFoundException error) {
...
} catch (IOException error) {
...
}
```
Exemple invalide si `FileNotFoundException extends IOException` :
```text
catch (IOException error) {
...
} catch (FileNotFoundException error) {
...
}
```
Un ensemble de `catch` n'a pas à être exhaustif. Toute `Exception` non capturée continue à se propager et doit être couverte par le contrat `throws` de la callable englobante.
Les variables de `catch` suivent les règles normales de scope et de non-shadowing. Des `catch` distincts peuvent réutiliser le même nom parce que leurs scopes sont disjoints.
## 18.11 `finally` non-escaping — V1 REQUIS — FIGÉ
`finally` exécute un bloc commun avant de quitter la construction `try/catch`, qu'il y ait :
```text
fin normale du try
fin normale d'un catch
return traversant la construction
throw propagé
break / continue traversant la construction
Exception non capturée par les catch
```
`finally` ne doit jamais remplacer une sortie déjà en cours. Les sorties structurées suivantes y sont interdites :
```text
return
throw
break
continue
emit
```
Aucune `Exception` non capturée ne peut sortir indirectement d'un `finally`. Toute callable appelée depuis `finally` dont le contrat comporte `throws` doit avoir ses exceptions entièrement gérées à l'intérieur du `finally`.
Une faute runtime non récupérable reste distincte de ce contrat d'exception.
## 18.12 Faute runtime / panic — V1 REQUIS — À FINALISER
Les violations de contrat du langage telles que :
```text
index hors limites
division entière par zéro
overflow checked
représentation mémoire invalide
borne dynamique invalide lors d'une construction directe lorsque la règle du type le définit
```
ne sont pas nécessairement des `ResultError` ou des `Exception` récupérables.
Le modèle exact de faute runtime/fatal error/panic et son interaction avec cleanup/destruction doit être défini avant la finalisation V1.

428
chapters/019-controle-de-flux.md Normal file
View File

@@ -0,0 +1,428 @@
# 19. Contrôle de flux
## 19.1 `if` / `elseif` / `else` — V1 REQUIS — FIGÉ
Les conditions sont obligatoirement de type `bool`. Saselang n'a aucune notion de truthiness/falsiness implicite.
Les parenthèses autour de chaque condition et les accolades autour de chaque bloc sont obligatoires, y compris pour un bloc contenant un seul statement.
La seule chaîne conditionnelle canonique est :
```text
if (condition) {
action();
} elseif (otherCondition) {
otherAction();
} else {
fallback();
}
```
La forme `else if` n'existe pas en Saselang. `elif` n'est pas un alias de `elseif`.
Un `if` sans `emit` est uniquement une structure de contrôle et ne produit aucune valeur.
Un `if` qui contient `emit` devient un `if` producteur de valeur. Dans ce cas :
- le résultat du `if` doit obligatoirement être affecté à une destination ;
- un bloc `else` final est obligatoire ;
- chaque voie de terminaison normale de chaque branche doit produire explicitement une valeur via `emit` ;
- une voie que le compilateur prouve comme terminant définitivement le contrôle (`return`, `throw`, runtime fault certain ou non-terminaison prouvée) n'a pas à exécuter `emit` ;
- les valeurs émises doivent être compatibles avec le type de la destination ;
- aucune valeur de secours n'est implicite, y compris pour `Option<T>`.
Exemple :
```text
int32 result = if (x > 10) {
emit 1;
} elseif (x > 5) {
emit 2;
} else {
emit 3;
};
```
Pour un `Option<T>`, l'absence doit également être explicitement produite :
```text
Option<uint32> result = if (condition) {
emit Option::Some(42);
} else {
emit Option::None;
};
```
Une branche qui termine définitivement le contrôle ne rejoint pas l'affectation de sortie et n'a donc pas à produire de valeur. Cette règle améliore la preuve de contrôle de flux sans introduire de valeur implicite.
## 19.2 `match` — V1 REQUIS — FIGÉ
`match` remplace `switch/case` pour la sélection par valeur ou structure.
Forme générale :
```text
match (value) {
pattern1 => {
statements;
}
pattern2 => {
statements;
}
_ => {
statements;
}
}
```
L'expression entre parenthèses est évaluée exactement une fois. Le `match` examine ensuite cette valeur selon les patterns déclarés ; il ne réévalue pas l'expression pour chaque branche.
Dans une branche, tout ce qui constitue syntaxiquement le pattern se situe avant `=>`. `=>` est un séparateur grammatical, pas un opérateur.
Les patterns d'un même `match` ne doivent pas se chevaucher. Une valeur possible ne peut donc correspondre qu'à une seule branche. L'ordre des branches ne sert pas à résoudre des chevauchements : un chevauchement détectable est une erreur de compilation.
Le `match` doit être exhaustif :
- si les patterns explicites couvrent toutes les valeurs possibles, une branche finale `_` est interdite car elle serait inaccessible ;
- si les patterns explicites ne couvrent pas toutes les valeurs possibles, une branche finale `_` est obligatoire ;
- lorsqu'elle existe, `_` est nécessairement la dernière branche.
`_` signifie alors « toutes les valeurs restantes non couvertes par les autres patterns ».
Il n'existe ni `case`, ni `default`, ni fallthrough. `break` ne sert pas à quitter un `match` ; il reste un contrôle de boucle.
Le matching n'exécute pas de code utilisateur caché, de prédicat arbitraire ou de conversion implicite pour décider si une branche correspond. Un pattern décrit directement une valeur, un ensemble de valeurs ou une structure que le compilateur peut examiner à partir de la valeur déjà évaluée.
Les classes ne constituent pas des patterns de sélection dynamique. Une relation de sous-typage comme `Dog is Animal` créerait naturellement des ensembles chevauchants et contredirait la règle de non-chevauchement. Les tests dynamiques de classe utilisent `is` avec `if`/`elseif`/`else`.
Une classe peut néanmoins être la valeur capturée par un binding lorsque le type statique d'un payload ou d'un champ est déjà cette classe ; cela n'effectue alors aucun test dynamique de classe.
## 19.3 Patterns — V1 REQUIS — FIGÉ EN PRINCIPE
Les catégories de patterns déjà figées sont :
```text
literal pattern
enum variant pattern
tuple pattern
struct pattern
typed binding pattern
wildcard _
alternative pattern avec |
nested pattern
Range pattern si et seulement si le Range est valide selon les règles de Range
```
Les constantes nommées et les détails de compatibilité des littéraux restent à harmoniser avec les règles générales des constantes et des types ; ils ne doivent pas introduire d'évaluation utilisateur cachée.
### 19.3.1 Alternatives avec `|`
Dans un pattern, `|` est un séparateur grammatical d'alternatives et non l'opérateur booléen `||` ni l'opérateur bitwise `|`.
```text
1 | 2 | 3 => {
...
}
```
Les alternatives d'une même branche doivent elles-mêmes être non chevauchantes, et elles ne doivent chevaucher aucune autre branche.
Lorsque des alternatives créent des bindings, toutes les alternatives doivent créer exactement les mêmes bindings, avec les mêmes noms et les mêmes types :
```text
A(uint32 value) | B(uint32 value) => {
use(value);
}
```
est admissible si `A` et `B` sont des variantes distinctes compatibles, alors que les formes où le type ou l'ensemble des bindings change entre alternatives sont interdites.
### 19.3.2 Enum patterns
Une variante sans payload peut être utilisée directement :
```text
Color::Red => {
...
}
```
Une variante avec payload peut contenir des sous-patterns. Une capture est un binding typé explicite :
```text
Result::Ok(uint32 value) => {
use(value);
}
Result::Err(Error error) => {
handle(error);
}
```
La forme `Result::Ok(value)` n'introduit pas implicitement le type de `value` : les variables créées par un pattern respectent la règle générale de typage explicite.
`_` peut être utilisé comme sous-pattern pour ignorer explicitement un payload ou un composant :
```text
Result::Ok(_) => {
...
}
```
### 19.3.3 Tuple patterns
Un tuple peut être décomposé positionnellement en sous-patterns de même arité :
```text
(0, 0) => {
origin();
}
(int32 x, 0) => {
horizontal(x);
}
(int32 x, int32 y) => {
other(x, y);
}
```
Les bindings sont typés explicitement et leur scope est limité au bloc de leur branche.
### 19.3.4 Struct patterns
Un struct se déstructure nominalement par ses champs. Le nom du champ est placé à gauche de `:` et le sous-pattern appliqué à sa valeur à droite :
```text
Point {
x: 0,
y: int32 vertical
} => {
use(vertical);
}
```
Tous les champs du struct doivent être mentionnés exactement une fois dans le pattern. Il n'existe pas de `..` implicite pour ignorer les champs restants. Un champ ignoré doit l'être explicitement avec `_` :
```text
Point {
x: 0,
y: _
}
```
L'ordre des champs n'est pas sémantique puisque les noms les identifient.
La destructuration respecte les règles de visibilité normales. `match` ne permet jamais d'accéder à un champ inaccessible depuis le contexte courant.
### 19.3.5 Bindings, scopes et imbrication
Un binding créé par un pattern constitue une déclaration locale typée et obéit aux règles normales de non-shadowing.
Deux branches différentes peuvent employer le même nom de binding parce que leurs scopes sont disjoints, sauf si un symbole de même nom reste déjà visible depuis un scope englobant.
Les patterns sont récursivement imbriquables : tout emplacement qui accepte un sous-pattern peut recevoir un autre pattern compatible avec le type de la sous-valeur.
```text
SomeEnum::PointValue(
Point {
x: 0,
y: int32 y
}
) => {
use(y);
}
```
Les classes restent exclues comme test de pattern dynamique, même lorsqu'elles apparaissent comme type statique d'un binding.
### 19.3.6 Guards — REJETÉ
Saselang n'ajoute pas de guard `when` ou `if` au pattern.
Une condition métier supplémentaire est écrite explicitement dans le bloc de la branche avec le `if` normal. Cela évite d'introduire une deuxième phase de sélection, des chevauchements conditionnels runtime et une complexité supplémentaire dans l'analyse d'exhaustivité.
## 19.4 `emit` dans `if` et `match` — V1 REQUIS — FIGÉ
`emit` produit explicitement la valeur de la construction productrice courante sans quitter la fonction. Il est distinct de `return`.
Un `if` ou un `match` sans `emit` est une structure de contrôle et ne produit aucune valeur.
Dès qu'un `emit` est utilisé dans un `if` ou un `match` :
- la construction devient productrice de valeur ;
- cette valeur doit obligatoirement être affectée, soit lors d'une déclaration, soit par une affectation à une destination existante ;
- toutes les voies de terminaison normale de toutes les branches doivent produire explicitement une valeur compatible avec le type de destination ;
- une voie prouvée comme terminant définitivement le contrôle n'a pas à exécuter `emit` ;
- aucune valeur n'est produite implicitement.
Exemples :
```text
int32 result = match (value) {
0 => {
emit 10;
}
_ => {
emit 20;
}
};
```
```text
int32 result;
result = if (condition) {
emit 1;
} else {
emit 2;
};
```
Le rôle du compilateur s'arrête à la validité de l'affectation et du contrôle de flux. Il n'est pas requis que la variable destination soit ensuite effectivement utilisée.
## 19.5 `return`, `break`, `continue`, `yield` — V1 REQUIS / RÉSERVÉ
```text
return V1 requis
break V1 requis
continue V1 requis
yield réservé pour generators/coroutines si non finalisé en V1
```
`break;` et `continue;` sont des statements terminés par `;`. Les labels de boucle ne font pas partie du noyau V1 actuellement retenu.
## 19.6 Boucles — V1 REQUIS — FIGÉ
Saselang fournit exactement les formes générales suivantes pour les boucles de base :
```text
while (condition) {
...
}
dowhile (condition) {
...
}
for (initialization; condition; update) {
...
}
foreach (Type item in iterable) {
...
}
```
Pour toutes ces constructions, les parenthèses d'en-tête et les accolades du corps sont obligatoires.
Les conditions de `while`, `dowhile` et `for` sont obligatoirement de type `bool`.
`while` évalue sa condition avant chaque itération.
`dowhile` exécute le corps au moins une fois puis évalue sa condition après chaque itération, malgré la position syntaxique de la condition avant le bloc :
```text
dowhile (condition) {
statements;
}
```
La forme historique `do { ... } while (...);` n'existe pas. `do` reste `reserved-foreign` et interdit comme identifiant.
### 19.6.1 `for`
La condition centrale du `for` est obligatoire. La forme :
```text
for (;;) {
...
}
```
est interdite. Le compilateur doit orienter vers :
```text
while (true) {
...
}
```
pour une boucle inconditionnelle.
Les zones `initialization` et `update` peuvent contenir plusieurs éléments séparés par des virgules :
```text
for (i = 0, j = 5; i < x || j < y; i += 1, j += 1) {
...
}
```
Dans ce contexte, la virgule est un séparateur grammatical de la liste d'initialisation ou de mise à jour ; Saselang n'introduit pas d'opérateur virgule général.
Les virgules finales restent interdites. La condition centrale reste une seule expression booléenne, même lorsque les zones d'initialisation ou de mise à jour contiennent plusieurs éléments.
La liste exacte des formes de statement admises dans les zones d'initialisation et de mise à jour doit rester cohérente avec la grammaire générale des statements ; aucune expression pure ne reçoit implicitement un effet de bord.
### 19.6.2 `foreach`
La forme canonique est :
```text
foreach (Type item in iterable) {
...
}
```
Le type du binding est explicite ; `foreach (item in iterable)` sans type n'est pas admis.
`in` est un mot-clé Saselang actif dans cette construction.
`foreach` s'appuie sur les interfaces Core `Iterable<T>` / `Iterator<T>`. La variable d'itération appartient au scope du bloc de boucle.
### 19.6.3 Formes redondantes rejetées
Saselang n'ajoute pas de synonymes de boucle ou de condition lorsqu'une construction existante exprime déjà la même sémantique :
```text
until (...) -> utiliser while (!...)
repeat ... until -> utiliser dowhile (!...)
unless (...) -> utiliser if (!...)
loop { ... } -> utiliser while (true) { ... }
```
Ces mots peuvent rester `reserved-foreign` pour éviter les collisions avec d'autres langages, sans devenir des mots-clés actifs Saselang.
## 19.7 Statements, blocs et terminateurs — V1 REQUIS — FIGÉ
Le point-virgule `;` marque exclusivement la fin d'un statement ou d'une déclaration sans corps qui exige un terminateur. Il n'est jamais un séparateur vide ou décoratif.
Sont interdits :
```text
;
;;
foo();;
```
Une construction terminée par un bloc `{ ... }` ne reçoit pas de `;` supplémentaire. Les accolades ferment déjà le bloc.
Les blocs de contrôle utilisent toujours `{ ... }`. Un bloc anonyme à l'intérieur d'une callable suit la même règle et n'est pas suivi de `;`.
Les virgules séparent deux éléments ; Saselang n'autorise pas les trailing commas. Ainsi :
```text
foo(first, second, third); // valide
foo(first, second, third,); // invalide
```
Cette règle vaut pour les listes grammaticales correspondantes : arguments, paramètres, éléments de tuple/array, paramètres génériques et autres listes définies par la grammaire. Les listes spécifiques de `for` suivent la même absence de virgule finale.
Les retours à la ligne, espaces, tabs et indentation n'ont aucune signification grammaticale. Hors contenu textuel significatif, une construction peut être placée sur une seule ligne sans changer sa sémantique.
## 19.8 `switch/case` — REJETÉ
Pas de `switch/case` C/Java avec fallthrough. `match` couvre la sélection structurelle sans `case`, `default` ni chute implicite.

365
chapters/020-operateurs.md Normal file
View File

@@ -0,0 +1,365 @@
# 20. Opérateurs
## 20.1 Principe — V1 REQUIS — FIGÉ
Les opérateurs utilisateur ne peuvent être fournis que via un ensemble fermé d'interfaces Core compiler-known préfixées `Op`.
L'utilisateur ne peut pas inventer de nouveaux symboles opérateurs.
Les `operator` contracts :
- retournent directement leur valeur ;
- ne retournent jamais `Result` ;
- ne déclarent jamais `throws`.
Une faute de contrat du langage peut néanmoins déclencher une faute runtime déterministe.
## 20.2 Interfaces arithmétiques — V1 REQUIS — FIGÉ
```text
OpPositive<T>
OpNegate<T>
OpAdd<Lhs,Rhs,Out>
OpSubtract<Lhs,Rhs,Out>
OpMultiply<Lhs,Rhs,Out>
OpDivide<Lhs,Rhs,Out>
OpRemainder<Lhs,Rhs,Out>
```
Les opérations binaires peuvent être hétérogènes.
Exemples légitimes :
```text
Vector3 * float64 -> Vector3
Matrix * Vector3 -> Vector3
Timestamp + Duration -> Timestamp
Timestamp - Timestamp -> Duration
```
L'ordre compte : `A op B` est distinct de `B op A`.
## 20.3 Interfaces bitwise — V1 REQUIS — FIGÉ
```text
OpBitNot<T>
OpBitAnd<Lhs,Rhs,Out>
OpBitOr<Lhs,Rhs,Out>
OpBitXor<Lhs,Rhs,Out>
OpShiftLeft<T,Out>
OpShiftRight<T,Out>
```
Pour les primitives numériques, `& | ^` exigent les mêmes types primitifs exacts, sans promotion implicite.
Les shifts primitifs utilisent initialement `uint32` comme type de count.
Count hors largeur :
```text
statique -> erreur compilation
dynamique -> faute runtime
```
`>>` :
```text
unsigned -> logical zero-fill
signed -> arithmetic sign extension
```
Pas de `>>>`.
## 20.4 Logique booléenne — V1 REQUIS — FIGÉ
Short-circuit :
```text
!a
a && b
a || b
```
Eager :
```text
a & b
a | b
a ^ b
```
`&&`, `||` et `!` ne sont pas surchargeables.
`&`, `|`, `^` ont une sémantique intrinsèque eager pour `bool`, bitwise pour les primitives entières et peuvent utiliser les contrats `OpBit...` sur types utilisateur.
Pas de NAND/NOR natifs.
## 20.5 Égalité — V1 REQUIS — FIGÉ EN PRINCIPE
```text
OpPartialEqual<Lhs,Rhs>
OpEqual<T>
```
`OpEqual<T>` renforce :
```text
OpPartialEqual<T,T>
```
et garantit contractuellement une relation d'équivalence :
```text
réflexive
symétrique
transitive
```
`float*` n'est pas `OpEqual` au sens strict si NaN brise la réflexivité ; il relève de l'égalité partielle.
`!=` est toujours dérivé de `==`, jamais implémenté indépendamment.
Les classes ne reçoivent aucune comparaison champ-à-champ automatique : elles doivent choisir explicitement leur sémantique d'égalité si elles veulent supporter `==`.
## 20.6 Comparaison — V1 REQUIS — FIGÉ EN PRINCIPE
Core :
```text
public enum Ordering {
Less,
Equal,
Greater,
Unordered
}
```
Interfaces :
```text
OpPartialCompare<Lhs,Rhs>
OpCompare<T>
```
`OpCompare<T>` renforce `OpPartialCompare<T,T>` et garantit un ordre total, donc pas de `Ordering::Unordered`.
Les floats utilisent l'ordre partiel ; les entiers peuvent utiliser l'ordre total.
Le lien exact entre égalité et comparaison pour éviter deux contrats contradictoires sur une même paire doit être verrouillé dans la spécification finale des interfaces `Op`.
## 20.7 Comparaisons hétérogènes — V1 REQUIS — FIGÉ EN PRINCIPE
Saselang doit conserver la possibilité d'égalité/comparaison hétérogène.
La forme exacte des paramètres génériques et les règles de symétrie automatique doivent encore être formalisées pour éviter les implémentations concurrentes incohérentes.
## 20.8 Ownership des implémentations opérateur — V1 REQUIS — FIGÉ EN PRINCIPE
Direction :
- normalement l'implémentation appartient au type nominal de gauche ;
- si le LHS est une primitive/Core sealed non extensible, le type nominal de droite peut fournir une forme inverse explicitement permise ;
- un troisième package ne peut pas définir arbitrairement un opérateur entre deux types externes ;
- une seule implémentation canonique par `(operator,Lhs,Rhs)`.
Les détails doivent être alignés sur le resolver des packages.
## 20.9 Indexation — V1 REQUIS — FIGÉ
```text
OpIndex<Index,Read>
OpIndexMut<Index,Write>
```
Les deux contrats sont indépendants.
Syntaxe :
```text
container[index]
container[index] = value
```
Les séquences standard utilisent initialement `uint64` comme index.
D'autres index numériques pourront être supportés ultérieurement sans modifier la largeur de `uint64`.
Un type utilisateur peut utiliser n'importe quel type d'index pertinent.
## 20.10 Map — V1 REQUIS — DIRECTION FIGÉE
Direction recommandée :
```text
Map<K,V>
OpIndex<K,Option<V>>
OpIndexMut<K,V>
```
Lecture : absent -> `None` ; présent -> `Some(value)`.
Écriture : insertion si absent, remplacement si présent.
Une méthode `containsKey` peut compléter l'API sans être obligatoire avant toute lecture.
## 20.11 Affectation — V1 REQUIS — FIGÉ
`=` n'est pas une expression.
Interdits :
```text
if (a = b) { ... }
x = (a = b);
a = b = c;
```
## 20.12 Affectations composées — V1 REQUIS — FIGÉ
```text
+= -= *= /= %=
&= |= ^=
<<= >>=
```
Elles n'ont aucun `Op...` propre et ne sont donc pas surchargeables directement.
Elles sont composées de :
```text
lecture
+ opérateur fondamental surchargeable
+ réaffectation
```
Le résultat de l'opération doit être assignable exactement à la destination.
Aucune conversion implicite ne doit être inventée pour rendre l'affectation composée valide.
## 20.13 `is` — V1 REQUIS — FIGÉ
`is` teste l'appartenance d'une valeur à un type polymorphe ou à l'un de ses sous-types runtime.
```text
value is Type
```
Pour une instance runtime de `Labrador` avec `Labrador extends Dog` et `Dog extends Animal` :
```text
value is Animal // true
value is Dog // true
value is Labrador // true
```
`is` est utilisable sur les classes et les interfaces lorsqu'un polymorphisme runtime existe. Il est interdit sur les types sans polymorphisme runtime tels que les primitives numériques, `char`, les structs, les enums, les tuples ou les unions.
`is` n'est pas surchargeable.
Dans une branche dont la condition positive prouve `value is Type`, le compilateur raffine `value` vers `Type` dans le scope correspondant. Le raffinement cesse avec ce scope.
Saselang n'introduit pas `is not` : la négation générale s'écrit explicitement :
```text
!(value is Type)
```
## 20.14 `instanceof` — V1 REQUIS — FIGÉ
`instanceof` teste le **type de classe runtime exact**.
```text
value instanceof ConcreteClass
```
Pour une instance runtime exacte de `Labrador` :
```text
value instanceof Animal // false
value instanceof Dog // false
value instanceof Labrador // true
```
`instanceof` est utilisable uniquement avec une classe concrète non abstraite. Il est interdit avec une interface, une classe abstraite et tout type sans identité de classe runtime.
`instanceof` n'est pas surchargeable.
Une branche positive raffine la valeur vers la classe concrète testée et établit en plus que son type runtime est exactement cette classe.
Saselang n'introduit pas `not instanceof` :
```text
!(value instanceof ConcreteClass)
```
`is` et `instanceof` coexistent parce qu'ils ont deux sémantiques différentes : appartenance à une hiérarchie pour `is`, identité exacte de classe runtime pour `instanceof`.
## 20.15 `bitcast<T>` — V1 REQUIS — FIGÉ EN PRINCIPE
```text
bitcast<T>(value)
```
est un intrinsic compiler-known, pas un opérateur.
Il préserve exactement les bits et exige des tailles compatibles.
Il ne réalise aucune conversion numérique.
Certains bitcasts sont sûrs lorsque tout motif de bits destination est valide ; d'autres nécessiteront `unsafe`.
Le tableau exact doit être lié au modèle mémoire.
## 20.16 Appel `()` — V1 REQUIS — FIGÉ EN PRINCIPE
`()` est une construction d'appel du langage, pas un opérateur utilisateur.
Il n'est pas prévu de fournir un `OpCall` général.
Les fonctions, closures/lambdas futures seront appelables par définition de leur type, pas en surchargeant arbitrairement `()` sur n'importe quel objet.
## 20.17 Précédence — V1 REQUIS — FIGÉ
Du plus fort au plus faible :
```text
1. qualification / membre . ::
2. appel / indexation () []
3. préfixes +x -x !x ~x
4. multiplicatifs * / %
5. additifs + -
6. shifts << >>
7. relation / type < <= > >= is instanceof
8. égalité == !=
9. bitwise AND &
10. bitwise XOR ^
11. bitwise OR |
12. logique short-circuit AND &&
13. logique short-circuit OR ||
```
`bitcast<T>(...)` suit la syntaxe d'appel et n'a pas sa propre précédence.
`=` et les affectations composées ne figurent pas dans cette hiérarchie puisqu'elles ne produisent pas de valeur.
## 20.18 Associativité — V1 REQUIS — FIGÉ
Les opérateurs binaires arithmétiques/bitwise/logiques sont associatifs syntaxiquement à gauche.
Les préfixes s'imbriquent depuis la droite.
Les comparaisons sont non associatives :
```text
a < b < c -> interdit
a == b == c -> interdit
```
Écrire explicitement :
```text
a < b && b < c
```
---

170
chapters/021-strings-unicode-et-encodages.md Normal file
View File

@@ -0,0 +1,170 @@
# 21. Strings, Unicode et encodages
## 21.1 `String` — V1 REQUIS — FIGÉ EN PRINCIPE
`String` est le type ordinaire de texte Unicode.
La représentation interne peut varier suivant le backend/target, mais la sémantique observable doit rester identique.
## 21.2 Encodages explicites — V1 REQUIS — DIRECTION FIGÉE
Les encodages explicites appartiennent au SDK, pas au langage :
```text
Utf8String
Utf16String
Utf32String
AsciiString éventuel
Bytes
```
Les conversions avec `String` doivent être explicites et définies.
## 21.3 Indexation String — V1 REQUIS — À FINALISER
Il faut décider avant V1 ce que signifie l'accès au texte :
```text
byte
code unit
Unicode scalar
code point
grapheme cluster
```
Ne pas déclarer implicitement `String : OpIndex<uint64,char>` avant cette décision.
## 21.4 `char` — V1 REQUIS — FIGÉ
`char` représente exactement un Unicode scalar value, et non un octet, une unité UTF-8/UTF-16 ou un grapheme utilisateur complet.
Exemples valides :
```text
'A'
'é'
'中'
'😀'
'\n'
'\u{1F600}'
```
Après traitement des escapes, un littéral `char` doit contenir exactement un scalar. `''`, `'ab'` ou une séquence produisant plusieurs scalars sont invalides.
Saselang n'effectue aucune normalisation Unicode implicite des littéraux ; NFC/NFD et autres transformations relèvent d'opérations explicites de bibliothèque.
## 21.5 Familles de littéraux texte — V1 REQUIS / RÉSERVÉ
Les familles suivantes sont reconnues ou réservées parce qu'elles représentent des sémantiques distinctes et non des alias gratuits :
```text
"..." String normale, escapes actifs
"""...""" String normale multiligne
r"..." String brute
r"""...""" String brute multiligne
i"..." String interpolée
i"""...""" String interpolée multiligne
ir"..." interpolation + contenu brut, réservé
b"..." bytes, réservé
br"..." bytes bruts, réservé
u8"..." texte encodé UTF-8 explicitement, réservé
u16"..." texte encodé UTF-16 explicitement, réservé
u32"..." texte encodé UTF-32 explicitement, réservé
c"..." chaîne compatible C, réservé
cr"..." chaîne C brute, réservé
t"..." template structuré, réservé
```
V1 doit au minimum couvrir les formes normales, multilignes, raw et interpolées. Les formes bytes, encodages explicites, C string, template et certaines combinaisons peuvent être implémentées en V2 mais leur espace lexical est réservé dès V1.
Les préfixes de littéraux ne sont pas nécessairement des mots-clés globaux : ils sont reconnus comme préfixes lorsqu'ils sont immédiatement contigus au délimiteur correspondant.
Les combinaisons de préfixes ne sont pas arbitraires. Une matrice normative ultérieure doit classer chaque combinaison comme `supported`, `reserved` ou `forbidden/meaningless`, et retenir une seule orthographe canonique par combinaison. Des doublons tels que `ir` et `ri` pour une même sémantique ne coexistent pas.
La forme interpolée `i"..."` est réservée, mais le délimiteur interne de l'expression reste **V1 REQUIS — À FINALISER** entre :
```text
i"Hello {name}"
i"Hello ${name}"
```
Une seule de ces deux formes sera retenue comme syntaxe canonique. Une `String` non préfixée n'interprète jamais ces séquences comme interpolation.
## 21.6 Chaînes multilignes — V1 REQUIS — FIGÉ
Les triples quotes fournissent la forme multiligne :
```text
"""
first
second
"""
```
Le délimiteur de fermeture détermine l'indentation structurelle à retirer de chaque ligne. Une indentation supplémentaire volontaire dans le contenu est conservée.
Lorsque `"""` d'ouverture est immédiatement suivi d'un retour à la ligne, ce premier retour structurel n'appartient pas à la valeur. Lorsque le délimiteur de fermeture se trouve seul après l'indentation structurelle d'une nouvelle ligne, le dernier retour structurel est également supprimé.
La même règle de lignes et d'indentation s'applique aux variantes normales, raw et interpolées. Le caractère raw ou interpolé modifie le traitement du contenu, pas la structure multiligne.
Le formatter peut réindenter la structure source uniquement en préservant exactement la valeur sémantique du littéral.
## 21.7 Raw strings et délimiteurs — V1 REQUIS — FIGÉ
La forme raw utilise un préfixe `r` contigu et peut employer zéro ou plusieurs `#` comme partie du délimiteur :
```text
r"simple"
r#"He said "hello"."#
r##"contains "# inside"##
```
La fermeture reprend exactement le même nombre de `#` que l'ouverture. Aucun escape n'est interprété dans le contenu raw.
La même mécanique est disponible pour les triples quotes :
```text
r"""..."""
r#"""..."""#
```
Les `#` appartiennent au délimiteur lexical et ne sont pas des escapes. Les variantes combinées réservées telles que `ir`, `br` ou `cr` suivent le même principe lorsqu'elles seront activées.
Une borne d'implémentation raisonnable au nombre de `#` peut être imposée, à condition d'être documentée et diagnostiquée explicitement ; cette borne n'est pas encore normative.
`raw` est une propriété lexicale et ne change pas à elle seule le type résultat.
## 21.8 Escapes normaux — V1 REQUIS — FIGÉ
Dans les `String` normales et les `char`, l'ensemble canonique est :
```text
\\ backslash
\" double quote
\' single quote
\n newline
\r carriage return
\t horizontal tab
\0 NUL
\u{...} Unicode scalar
```
`\u{...}` contient de 1 à 6 chiffres hexadécimaux, n'accepte pas `_`, doit être inférieur ou égal à `0x10FFFF` et ne peut pas désigner la plage surrogate UTF-16 `0xD800..0xDFFF`.
Saselang n'introduit pas les alias historiques redondants `\uXXXX`, `\UXXXXXXXX`, les escapes octaux ou les control aliases C rares lorsque `\u{...}` couvre déjà leur besoin.
`\xNN` est réservé aux littéraux orientés octets, notamment `b"..."`, où il représente exactement un octet avec exactement deux chiffres hexadécimaux :
```text
b"\x00\x7f\x80\xff"
```
`\xNN` est interdit dans une `String` Unicode normale et dans `char`.
## 21.9 Unicode et représentation — V1 REQUIS — FIGÉ EN PRINCIPE
Le fichier source UTF-8 peut contenir directement des scalars Unicode valides dans `String`, `char`, commentaires et Saseldoc. Une séquence UTF-8 invalide est une erreur de source ; le compilateur ne la répare pas silencieusement.
La représentation physique interne de `String` reste indépendante de cette syntaxe source et peut varier selon backend/target conformément à la section 21.1.
---

220
chapters/022-collections-et-iteration.md Normal file
View File

@@ -0,0 +1,220 @@
# 22. Collections et itération
## 22.1 `Array<T>` — V1 REQUIS — DIRECTION FIGÉE
`Array<T>` est une séquence contiguë dont la taille est fixée lors de la création et n'est pas redimensionnable.
## 22.2 `StaticArray<T,N>` — V1 REQUIS — DIRECTION FIGÉE
`StaticArray<T,N>` est un tableau à taille connue à la compilation.
Le mécanisme exact de const generics nécessaire à `N` doit être défini avec les generics.
## 22.3 Collection redimensionnable — V1 REQUIS — À FINALISER
Un type du type :
```text
Vector<T>
```
est envisagé pour les séquences redimensionnables, mais l'API et le nom final doivent être figés dans le SDK V1.
## 22.4 `Iterable<T>` / `Iterator<T>` — V1 REQUIS — FIGÉ
Interfaces Core reconnues par `foreach`.
Elles ne portent pas le préfixe `Op`, car `foreach` est une construction du langage et non un opérateur symbolique.
Indexabilité et itérabilité sont indépendantes.
## 22.5 `Range<T>` — V1 REQUIS — FIGÉ EN PRINCIPE
`Range<T>` est une vraie valeur Saselang immuable représentant un intervalle ordonné. Il ne représente ni un pas ni une progression d'itération.
Les quatre syntaxes de bornes sont :
```text
a..b [a, b] bornes basse et haute incluses
a>..b (a, b] borne basse exclue, borne haute incluse
a..<b [a, b) borne basse incluse, borne haute exclue
a>..<b (a, b) bornes basse et haute exclues
```
Les deux bornes doivent avoir exactement le même type `T`. Saselang ne possède pas de `Range<L,U>` et ne recherche aucun type commun implicite entre deux bornes déjà typées différemment.
Un littéral non encore typé peut toutefois être contextualisé normalement :
```text
Range<uint64> ids = 1..100;
```
### 22.5.1 Domaine ordonné
`Range<T>` est disponible lorsque les valeurs admissibles utilisées comme bornes appartiennent à un domaine totalement ordonné selon le contrat de comparaison retenu par Saselang.
La règle est fondée sur la capacité du type, pas sur une whitelist fermée. Elle peut donc s'appliquer à des entiers, `char`, des enums ou structs explicitement ordonnés, et à des types Core/utilisateur satisfaisant le contrat requis.
Les enums n'obtiennent pas automatiquement un ordre à partir de leur ordre de déclaration : ils doivent fournir explicitement la capacité d'ordre total requise.
Les floats sont autorisés comme bornes de `Range<floatN>` uniquement pour leur sous-domaine fini :
```text
NaN interdit comme borne
+Infinity interdit comme borne
-Infinity interdit comme borne
valeur finie autorisée
```
`-0.0` et `+0.0` occupent la même position dans l'ordre numérique d'un range, même si leur représentation binaire reste distincte et observable par les mécanismes bas niveau appropriés.
`NaN` et les infinities n'appartiennent à aucun `Range<floatN>` défini avec ces règles ; `contains()` retourne donc `false` pour ces valeurs.
### 22.5.2 Construction et ranges vides
Les bornes sont évaluées de gauche à droite, exactement une fois chacune, avant la construction du range.
Une borne statiquement prouvée invalide provoque une erreur de compilation. Une borne calculée dynamiquement mais invalide selon le contrat de `Range<T>` provoque un runtime fault lors de la construction directe. Une API Core explicite retournant `Result` pourra être fournie lorsqu'une validation récupérable est souhaitée.
`lower > upper` ne constitue pas une erreur : le résultat est un range vide.
Lorsque les bornes sont égales :
```text
a..a contient exactement a
a>..a vide
a..<a vide
a>..<a vide
```
Un range vide est une valeur valide. En revanche, un range statiquement vide utilisé comme pattern de `match` est interdit parce que la branche serait inatteignable.
Les ranges ouverts/infinis tels que `..b`, `a..` ou `..` ne font pas partie de V1.
### 22.5.3 API fondamentale
`Range<T>` doit exposer au minimum les capacités conceptuelles suivantes, dont les noms sont retenus sauf raison ultérieure forte de les changer :
```text
range::lower()
range::upper()
range::includesLower()
range::includesUpper()
range::isEmpty()
range::contains(value)
```
Le range est immuable : modifier une borne signifie construire un autre `Range<T>`.
Le `match` utilisant un range-pattern emploie la même sémantique d'appartenance sans invoquer un prédicat utilisateur arbitraire.
## 22.6 Progression et itération des ranges — V1 REQUIS — FIGÉ EN PRINCIPE
L'existence d'un `Range<T>`, son itérabilité et sa progression sont trois concepts distincts :
```text
Range<T> intervalle ordonné
RangeIterable<T> parcours canonique vers l'avant
RangeStep<T,Step> parcours avant avec pas explicite
RangeReverse<T> parcours canonique vers l'arrière
RangeReverseStep<T,Step> parcours arrière avec pas explicite
RangeProgression<T,Step> valeur de progression produite
```
Ces noms sont retenus comme noms Core significatifs ; leur namespace exact sera décidé lors de l'organisation générale de Core, probablement dans une famille dédiée aux ranges.
Un type n'est pas obligé de fournir toutes ces capacités. Un range peut être valide sans être itérable ; il peut être itérable vers l'avant sans supporter `reverse()` ou `step()`.
`foreach` continue à consommer `Iterable<T>` : un `Range<T>` ou une `RangeProgression<T,Step>` n'est utilisable par `foreach` que lorsque les capacités Core concernées fournissent cette itérabilité.
### 22.6.1 Progression canonique
Lorsqu'un type fournit `RangeIterable<T>`, le parcours direct d'un range utilise sa progression canonique. Celle-ci n'est pas définie génériquement comme un appel caché à `step(1)`.
Pour les entiers Core, la progression canonique avance naturellement d'une unité. Pour `char`, elle avance parmi les Unicode scalar values valides et saute les valeurs surrogate `U+D800..U+DFFF`, qui ne sont pas des `char` Saselang valides.
Un `Range<floatN>` est un intervalle valide lorsque ses bornes sont finies, mais il n'est pas automatiquement itérable et ne reçoit pas automatiquement une capacité de `step` flottant.
### 22.6.2 `step(...)`
Le pas ne fait jamais partie du `Range`. La syntaxe de parcours explicite est :
```text
(range)::step(step)
```
Elle produit une progression itérable et ne modifie pas le `Range` d'origine.
La compatibilité entre le type des bornes `T` et le type du pas `Step` est définie explicitement par `RangeStep<T,Step>` ou `RangeReverseStep<T,Step>`. Elle n'est pas déduite automatiquement d'une conversion numérique générale.
Cela permet notamment de définir des couples adaptés au domaine :
```text
RangeStep<int32,int32>
RangeStep<int32,uint32>
RangeStep<char,uint32>
RangeStep<Date,Duration>
```
et de refuser des couples qui introduiraient une perte ou n'auraient pas de sens. Par exemple, un range `float16` peut recevoir seulement les types de pas explicitement supportés sans imposer qu'un `float32` plus large soit accepté.
Le pas exprime une magnitude de progression, pas une direction. Pour les types numériques Core, il doit être strictement supérieur à zéro. Un pas statiquement nul ou négatif est une erreur de compilation ; une valeur dynamique invalide provoque un runtime fault lors de la construction directe de la progression. Une API explicite en `Result` pourra exister pour une validation récupérable.
Pour les types utilisateur, la validité du pas est définie par le contrat Range correspondant et n'est pas réduite artificiellement à une comparaison numérique avec zéro.
### 22.6.3 `reverse()`
La direction inverse est explicite :
```text
(range)::reverse()
(range)::reverse()::step(step)
```
`reverse()` ne construit pas un range aux bornes inversées. Le `Range` reste identique ; seule la direction de parcours change.
La forme canonique compose la direction avant le pas :
```text
range
[::reverse()]
[::step(step)]
```
Une progression déjà matérialisée par `step()` n'est pas requise de fournir à son tour `reverse()`. Cela évite plusieurs chaînes d'appels synonymes pour le même parcours.
L'inclusion ou l'exclusion des bornes reste une propriété du range et ne change jamais avec la direction.
### 22.6.4 Arrêt, overflow et pas non aligné
Une progression s'arrête avant de produire une valeur hors du range. Elle ne doit jamais provoquer un overflow uniquement pour constater qu'elle a atteint la fin.
Par exemple :
```text
(250u8..255u8)::step(2u8)
```
produit conceptuellement :
```text
250 252 254
```
sans tenter de former `256`.
De même :
```text
(1..10)::step(4)
```
produit :
```text
1 5 9
```
La borne finale n'est pas ajoutée artificiellement si elle ne tombe pas naturellement sur la progression.
Un range vide produit simplement une progression vide.

95
chapters/023-optiont-et-nullablet.md Normal file
View File

@@ -0,0 +1,95 @@
# 23. `Option<T>` et `Nullable<T>`
## 23.1 Deux concepts distincts — V1 REQUIS — FIGÉ EN PRINCIPE
`Option<T>` et `Nullable<T>` ne sont ni des alias ni deux syntaxes pour la même idée.
`Option<T>` exprime une absence sémantique explicite : une valeur est présente (`Some`) ou absente (`None`). Il est conceptuellement un type algébrique Core disponible pour tout `T` compatible avec les autres règles du langage.
```text
Option<int32>
Option<String>
Option<MyStruct>
Option<MyClass>
```
La forme canonique de l'absence est qualifiée :
```text
Option<MyClass>::None
```
`Nullable<T>` exprime au contraire qu'un type `T` possède une représentation nulle admissible dans le modèle mémoire/ABI. Il n'ajoute pas une absence métier générique à n'importe quel type.
La forme canonique de la valeur nulle est :
```text
Nullable<MyClass>::Null
```
Le mot étranger `null` reste réservé/interdit comme identifiant mais n'a aucune sémantique Saselang. `Null` n'est pas une valeur globale magique.
La syntaxe nullable courte :
```text
T?
```
est rejetée. Saselang utilise explicitement `Nullable<T>`.
## 23.2 Composition — V1 REQUIS — FIGÉ
Les compositions suivantes sont distinguées explicitement :
```text
Option<Nullable<MyClass>> autorisé
Nullable<Option<MyClass>> interdit
Nullable<Nullable<MyClass>> interdit
```
`Option<Nullable<MyClass>>` peut représenter trois états sémantiquement distincts :
```text
Option::None
Option::Some(Nullable<MyClass>::Null)
Option::Some(instance non nulle)
```
`Nullable<Option<T>>` est interdit parce qu'`Option<T>` est un type algébrique qui possède déjà sa propre sémantique d'absence et n'est pas une cible intrinsèquement nullable.
`Nullable<Nullable<T>>` est interdit car il n'ajoute aucun état représentationnel utile.
Une optimisation physique éventuelle d'`Option<T>` utilisant une niche n'altère jamais cette sémantique et ne rend pas `Option<T>` nullable au niveau du langage.
## 23.3 Types admissibles pour `Nullable<T>` — V1 REQUIS — À FINALISER AVEC LE MODÈLE MÉMOIRE
`Nullable<T>` est autorisé uniquement lorsque `T` possède réellement une représentation nulle admissible selon le modèle mémoire/ABI Saselang.
Les catégories exactes doivent être fermées avec la mémoire et la FFI. Elles pourront notamment concerner des références de classes, raw pointers ou certains handles natifs, sans rendre automatiquement nullables les primitives numériques, `bool`, `char`, structs arbitraires ou types algébriques.
La distinction fondamentale est déjà figée :
```text
Option<T> absence sémantique
Nullable<T> nullabilité représentationnelle
```
## 23.4 Patterns et valeurs explicites — V1 REQUIS — FIGÉ EN PRINCIPE
`Option<T>` s'intègre naturellement au `match` par ses variantes :
```text
match (value) {
Option::Some(uint32 number) => {
...
}
Option::None => {
...
}
}
```
Aucune absence n'est produite implicitement par `if`, `match` ou `emit`.
`Option<Void>` et `Nullable<Void>` sont interdits conformément au statut spécial de `Void`.

126
chapters/024-casts-et-conversions.md Normal file
View File

@@ -0,0 +1,126 @@
# 24. Casts et conversions
## 24.1 Principe général — V1 REQUIS — FIGÉ EN PRINCIPE
Saselang distingue explicitement :
```text
conversion de valeur
cast de hiérarchie nominale
bitcast de représentation binaire
```
Ces mécanismes ne sont pas des alias.
`bitcast<T>(value)` est défini au chapitre 20 et ne constitue jamais une conversion numérique.
## 24.2 Conversions implicites numériques — V1 REQUIS — FIGÉ
Il n'existe aucune promotion numérique implicite générale entre deux valeurs déjà typées de types primitifs différents.
```text
int8 small = ...;
int32 large = small; // ERROR
int32 explicitLarge = small::toInt32(); // OK
```
Le typage contextuel d'un littéral non encore typé reste une règle distincte.
## 24.3 Upcast — V1 REQUIS — FIGÉ
Un upcast compatible dans une hiérarchie de classes ou vers une interface satisfaite est une assignation de sous-typage normale et ne nécessite pas une syntaxe de cast dédiée.
```text
Dog dog = ...;
Animal animal = dog;
Serializable serializable = dog;
```
## 24.4 Downcast et raffinement — V1 REQUIS — FIGÉ EN PRINCIPE
Le mécanisme canonique de downcast V1 est le test `is` suivi du raffinement de type dans le scope positif.
```text
Animal animal = ...;
if (animal is Dog) {
// animal est raffiné en Dog ici.
}
```
Lorsqu'un test du type runtime **exact** est nécessaire, `instanceof` est utilisé.
Saselang n'introduit pas pour le moment de syntaxe générale concurrente telle que `(Dog)value`, `value as Dog` ou `cast<Dog>(value)`. Une telle opération ne pourra être ajoutée que si un besoin distinct de `is`/`instanceof` + refinement est démontré et si son contrat d'échec est explicite.
## 24.5 API numérique du Core — V1 REQUIS — DIRECTION FIGÉE
Les conversions numériques sont exposées comme membres standard des primitives définis par le Core. Les noms de méthodes ne sont pas des mots-clés du langage.
Le compilateur connaît les règles nécessaires pour typer, vérifier, constant-fold et abaisser ces opérations vers Sase IR, mais l'inventaire exhaustif de la surface API appartient au Core.
Principe de nommage :
```text
toTarget()
conversion exacte et totale
tryToTarget()
conversion exacte pour la valeur courante, récupérable si impossible
roundToTarget()
perte de précision explicitement acceptée, conversion totale
tryRoundToTarget()
perte de précision explicitement acceptée, mais conversion pouvant échouer
saturateToTarget()
saturation explicite lorsqu'aucun arrondi supplémentaire n'est nécessaire
saturatingRoundToTarget()
arrondi + saturation explicitement annoncés
wrapToTarget()
wrapping entier explicite
```
Une forme n'existe que si elle apporte une sémantique observable différente d'une autre forme déjà disponible pour la paire source/destination.
Ainsi, lorsqu'un `toTarget()` exact et total existe, les variantes `tryToTarget()`, `saturateToTarget()` ou `wrapToTarget()` qui produiraient exactement le même résultat pour tout le domaine source sont absentes.
## 24.6 `float -> integer` — V1 REQUIS — DIRECTION FIGÉE
Un flottant ne possède jamais un simple `toIntXX()` ou `toUintXX()`.
La politique de passage du réel à l'entier doit être explicite, par exemple :
```text
tryExactToInt32()
tryFloorToInt32()
tryCeilToInt32()
tryRoundToInt32()
tryTruncateToInt32()
```
Les variantes saturantes ou wrapping, lorsqu'elles sont retenues, doivent également annoncer explicitement la politique mathématique appliquée.
Aucun comportement de conversion ne dépend d'un profil, d'un linter ou d'un backend.
## 24.7 `NumericConversionError` — V1 REQUIS — NOM DE TRAVAIL
`NumericConversionError` est retenu comme nom de travail du `ResultError` Core utilisé par les conversions numériques récupérables.
Son nom définitif, ses codes et son état minimal pourront encore être ajustés lors de la finalisation du Core sans modifier les principes de conversion de ce chapitre.
## 24.8 Matrice exhaustive — ANNEXE NORMATIVE EN COURS DE GEL
L'inventaire source → destination des opérations de conversion est maintenu séparément afin d'éviter les oublis, doublons et incohérences.
Voir :
```text
annexes/A-numeric-conversions.md
```
L'annexe doit lister le maximum de possibilités sémantiquement distinctes avant réduction finale de l'API Core.
---

13
chapters/025-lambdas-closures-callables-et-generators.md Normal file
View File

@@ -0,0 +1,13 @@
# 25. Lambdas, closures, callables et generators
## 25.1 Lambdas/closures — V1 REQUIS — À FINALISER
La V1 doit décider si les lambdas/closures font partie du langage initial. Elles sont fortement attendues mais leur syntaxe, capture, lifetime et type callable ne sont pas encore spécifiés.
Leur conception devra respecter la décision : pas de `OpCall` utilisateur général.
## 25.2 `yield` / generators — V1 RÉSERVÉ / À ÉVALUER
`yield` est réservé. Si les generators ne sont pas livrés dans V1, sa sémantique complète peut être reportée sans réutiliser le mot-clé.
---

23
chapters/026-async-et-concurrence.md Normal file
View File

@@ -0,0 +1,23 @@
# 26. Async et concurrence
## 26.1 Statut — V1 REQUIS — À FINALISER
Le modèle async/concurrency n'est pas encore spécifié.
Il faut décider au minimum :
```text
async/await ou autre modèle
Future/Promise Core ou SDK
threads natifs
structured concurrency éventuelle
cancellation
synchronisation
interaction avec Result/throws
interaction avec destruction déterministe
runtime minimal
```
Aucune dépendance obligatoire à un executor monolithique ne doit être supposée sans justification.
---

79
chapters/027-memoire-references-et-unsafe.md Normal file
View File

@@ -0,0 +1,79 @@
# 27. Mémoire, références et `unsafe`
## 27.1 GC obligatoire — REJETÉ
Pas de garbage collector obligatoire pour le modèle natif Saselang.
Un backend futur comme JVM peut utiliser son runtime interne à condition de préserver les garanties observables Saselang nécessaires.
## 27.2 Modèle mémoire — V1 REQUIS — À FINALISER CRITIQUE
Le modèle mémoire est un bloqueur majeur de V1.
Objectifs :
- ergonomie ordinaire proche des langages managed ;
- performances C/Rust-class lorsque possible ;
- ressources déterministes ;
- analyse interne ownership/move/escape possible ;
- pas de syntaxe de lifetimes omniprésente ;
- raw pointers explicites et unsafe.
Doivent être définis :
```text
value vs reference semantics
object allocation
moves/copies/clones
borrow/reference semantics si nécessaire
escape analysis
lifetimes internes
partial construction
partial destruction
cycles éventuels
resource ownership
thread-safety implications
```
## 27.3 `unsafe` — V1 REQUIS — FIGÉ EN PRINCIPE
`unsafe` ne désactive pas le système de types.
Il autorise uniquement une liste fermée d'opérations dont les garanties ne sont pas prouvables automatiquement.
Formes retenues :
```text
unsafe { ... }
unsafe func
unsafe method
unsafe clsmethod
unsafe construct
unsafe union
```
`unsafe` sur une callable décrit son contrat externe : l'appelant doit respecter des préconditions non vérifiables.
Une fonction sûre peut contenir localement un bloc `unsafe` si elle rétablit ses invariants avant de retourner.
Pas de modificateur général :
```text
unsafe variable
unsafe constant
unsafe field
```
Le caractère dangereux est porté par le type/opération.
## 27.4 Raw pointers — V1 REQUIS — À FINALISER
Les pointeurs bruts existent explicitement et leurs opérations de dereference/arithmétique autorisées doivent être précisément définies.
Les noms des types (`Ptr<T>`, `PtrMut<T>` ou autre) restent à figer.
## 27.5 Allocator — V1 REQUIS — À FINALISER CRITIQUE
Le modèle allocator doit être défini avec le modèle mémoire avant finalisation du runtime V1.
---

97
chapters/028-defer-et-nettoyage.md Normal file
View File

@@ -0,0 +1,97 @@
# 28. `defer` et nettoyage
## 28.1 `defer` — V1 REQUIS — FIGÉ
`defer` est lié au scope lexical dans lequel il est atteint. Il enregistre un cleanup exécuté à toute sortie de ce scope.
Exemple :
```text
{
acquireA();
defer {
releaseA();
}
acquireB();
defer {
releaseB();
}
work();
}
```
Les `defer` d'un même scope s'exécutent en ordre LIFO :
```text
releaseB();
releaseA();
```
Un `defer` n'est actif que si son statement a réellement été atteint pendant l'exécution.
Les sorties qui déclenchent les `defer` du scope traversé comprennent notamment :
```text
fin normale
return
throw
break
continue
emit quittant le scope concerné
```
La valeur d'un `return` ou d'un `emit` est déterminée avant l'exécution des cleanups nécessaires ; les `defer` ne peuvent pas la remplacer.
## 28.2 Unwind et ordre avec `catch` / `finally` — V1 REQUIS — FIGÉ
Lorsqu'une `Exception` quitte un scope, les `defer` des scopes abandonnés sont exécutés avant l'entrée dans le `catch` correspondant.
Ordre conceptuel :
```text
throw
-> unwind des scopes quittés
-> defer de ces scopes, LIFO
-> catch correspondant éventuel
-> defer du scope catch, LIFO
-> finally éventuel
-> continuation normale ou propagation
```
Chaque scope imbriqué possède sa propre pile LIFO et est entièrement déroulé avant de poursuivre le scope parent.
L'ordre exact entre `defer` et les futurs destructeurs automatiques sera finalisé avec le modèle mémoire/lifecycle, sans modifier la règle de scope LIFO propre à `defer`.
## 28.3 `defer` non-escaping — V1 REQUIS — FIGÉ
Comme `finally`, un bloc `defer` ne doit jamais remplacer une sortie déjà en cours.
Sont interdits dans un `defer` lorsqu'ils quittent le bloc :
```text
return
throw
break
continue
emit
```
Aucune `Exception` non capturée ne peut sortir indirectement d'un `defer`. Une callable appelée depuis un `defer` et susceptible de lancer une `Exception` doit voir cette exception entièrement gérée à l'intérieur du bloc `defer`.
Un `ResultError` reste une simple valeur : un appel retournant `Result<T,E>` est autorisé dans un `defer`, sous réserve des règles normales de traitement de cette valeur.
## 28.4 `finally` versus `defer` — V1 REQUIS — FIGÉ
`defer` sert au cleanup lexical lié à une acquisition ou à un scope local.
`finally` sert au bloc commun final d'une vraie construction `try/catch`.
Un `try/finally` sans `catch` est interdit précisément parce que `defer` couvre le besoin de cleanup systématique sans introduire une construction d'exception inutile.
## 28.5 `errdefer` — REJETÉ
Pas de `errdefer` séparé en V1.
`catch` gère les chemins d'`Exception`; `defer` gère le cleanup systématique du scope. Un troisième mécanisme serait redondant.

52
chapters/029-ffi-et-abi.md Normal file
View File

@@ -0,0 +1,52 @@
# 29. FFI et ABI
## 29.1 ABI C — V1 REQUIS — FIGÉ
Le premier ABI externe officiellement ciblé est C :
```text
extern "C"
```
## 29.2 `extern` — V1 REQUIS — FIGÉ EN PRINCIPE
`extern` est réservé aux déclarations qui représentent réellement une frontière de linkage/ABI.
Typiquement :
```text
extern "C" func
unsafe extern "C" func
extern "C" union
unsafe extern "C" union
```
Pas de `extern` décoratif sur classes/interfaces/méthodes ordinaires.
## 29.3 FFI safety — V1 REQUIS — FIGÉ EN PRINCIPE
Une fonction externe n'est pas automatiquement unsafe par simple fait d'être externe, mais toute API dont l'appelant doit respecter des invariants externes non vérifiables doit être déclarée `unsafe`.
## 29.4 Layout/interop — V1 REQUIS — À FINALISER
À définir :
```text
C struct layout
C enum mapping
raw pointers
strings C
callbacks
function pointers
calling conventions
variadic C
alignment/packing
ownership across FFI
error propagation across ABI
```
## 29.5 Dynamic loading — V1 RÉSERVÉ / SDK
Le chargement dynamique runtime (`dlopen`/LoadLibrary-like) est prévu comme fonctionnalité système/SDK et probablement unsafe, mais n'est pas une primitive fondamentale du langage.
---

33
chapters/030-reflexion-metadonnees-et-tests.md Normal file
View File

@@ -0,0 +1,33 @@
# 30. Réflexion, métadonnées et tests
## 30.1 `TypeInfo` / réflexion — V1 REQUIS — À FINALISER
Une réflexion minimale est attendue, mais son coût et son niveau doivent rester contrôlables.
Il faut distinguer :
```text
informations compiler-known
métadonnées conservées dans le binaire
réflexion runtime optionnelle
```
## 30.2 Tests — V1 REQUIS — FIGÉ EN PRINCIPE
Les tests ne doivent pas dépendre d'une réflexion runtime générale pour être découverts.
La toolchain doit pouvoir les identifier statiquement.
## 30.3 Métadonnées/annotations — V1 REQUIS — À FINALISER
Il faut définir une syntaxe propre pour les métadonnées de :
```text
compiler
test
documentation/tooling
```
Les transformations runtime cachées et les magic getters/setters restent défavorisés/rejetés.
---

101
chapters/031-fichiers-source-v1.md Normal file
View File

@@ -0,0 +1,101 @@
# 31. Fichiers source V1
## 31.1 `.saseltype` — V1 REQUIS — FIGÉ
- namespace obligatoire après en-tête/docs ;
- exactement un type nominal top-level parmi `class`, `struct`, `enum`, `interface`, `union` ;
- nom du fichier exactement identique au nom du type, extension exclue ;
- comparaison sensible à la casse même sur un filesystem qui ne l'est pas ;
- chemin relatif au `source_root` cohérent avec le namespace ;
- pas de fonctions/variables/constants top-level auxiliaires.
Exemple :
```text
src/compiler/lexer/Token.saseltype
namespace compiler.lexer;
public final class Token { ... }
```
## 31.2 `.sasel` — V1 REQUIS — FIGÉ
- namespace obligatoire et cohérent avec le répertoire ;
- imports ;
- fonctions libres ;
- variables/constants top-level ;
- pas de type nominal top-level ;
- nom de fichier ASCII minuscule suivant `[a-z][a-z0-9_]*.sasel` ;
- aucune correspondance obligatoire entre le nom du fichier et les symboles qu'il contient.
Un fichier `.sasel` peut porter le même nom qu'un sous-répertoire/sous-namespace voisin. Le nom du fichier ne participe pas à l'identité des symboles et la distinction `.` / `::` évite une ambiguïté de résolution.
## 31.3 `.saselrun` — V1 REQUIS — FIGÉ
Le point d'entrée source d'un package `bin` est obligatoirement :
```text
<source_root>/main.saselrun
```
Règles :
- directement sous `source_root` ;
- nom exact `main.saselrun` ;
- pas de namespace ;
- imports ;
- exactement `main` ;
- pas de helpers top-level ;
- exactement un `main.saselrun` par package `bin` ;
- `main.saselrun` interdit dans un package `lib`.
Cette règle évite d'introduire un champ de manifest destiné uniquement à choisir entre plusieurs points d'entrée concurrents.
## 31.4 `.saselscript` — V1 RÉSERVÉ
Extension réservée pour le futur environnement browser Saselang.
Direction actuelle :
- pas de namespace ;
- entrée browser ;
- plusieurs scripts possibles ;
- un script ne doit pas importer directement un autre `.saselscript` ;
- le code réutilisable doit venir de modules/libraries.
La V1 LLVM n'est pas obligée d'implémenter le runtime browser.
## 31.5 `module.saselmod` — V1 REQUIS — FIGÉ EN PRINCIPE
Nom exact :
```text
module.saselmod
```
Fichier entièrement optionnel.
S'il existe, il commence obligatoirement par une déclaration `namespace` correspondant exactement au répertoire.
Il ne contient :
- ni exports ;
- ni reexports ;
- ni dépendances de package ;
- ni options de build générales ;
- ni code exécutable arbitraire.
Un développeur voulant réexposer une API doit écrire un wrapper explicite.
Responsabilités prévues :
```text
doc module-wide
deprecated module-wide
policies module-wide (ex: forbid unsafe)
requirements de feature
target/capability requirements lorsque pertinent
```
Syntaxe précise de ces directives : V1 À FINALISER.
---

51
chapters/032-source-root-modules-et-namespaces.md Normal file
View File

@@ -0,0 +1,51 @@
# 32. Source root, modules et namespaces
## 32.1 Source root — V1 REQUIS — FIGÉ
Valeur par défaut :
```text
src
```
Configurable dans le manifest de package.
## 32.2 Module — V1 REQUIS — FIGÉ
Un module correspond à un répertoire relatif au `source_root`.
Un sous-répertoire représente un sous-module.
Un `module.saselmod` n'est pas nécessaire pour que le module existe.
## 32.3 Namespace — V1 REQUIS — FIGÉ
Le namespace correspond exactement au chemin relatif au `source_root`.
Exemple :
```text
src/saselang/compiler/lexer/Token.saseltype
```
contient :
```text
namespace saselang.compiler.lexer;
```
Le nom du package n'est pas automatiquement préfixé au namespace.
## 32.4 Segments de namespace — V1 REQUIS — FIGÉ
```regex
[a-z][a-z0-9_]*
```
ASCII lowercase uniquement.
Pas de `-` dans un segment de namespace.
Cette règle est volontairement différente de l'identité de package.
---

63
chapters/033-imports-et-resolution-des-noms.md Normal file
View File

@@ -0,0 +1,63 @@
# 33. Imports et résolution des noms
## 33.1 Imports — V1 REQUIS — FIGÉ
Imports file-level uniquement, après `namespace` lorsque celui-ci existe.
Pas de wildcard `*`.
Import symbole par symbole :
```text
import type saselang.compiler.lexer.Token;
import func saselang.compiler.lexer.tokenize;
import const saselang.compiler.config.MaxDepth;
import var saselang.runtime.state.CurrentMode;
```
`import type` couvre :
```text
class
struct
enum
interface
union
```
## 33.2 Alias — V1 REQUIS — FIGÉ
Sans `as`, le dernier nom devient l'alias local implicite.
```text
import type foo.Token;
```
importe `Token`.
Alias explicite :
```text
import type foo.Token as FooToken;
```
Les alias locaux doivent être uniques dans le fichier.
Pas d'alias de module.
## 33.3 Utilisation sans import — V1 REQUIS — FIGÉ
L'utilisation d'un chemin qualifié complet sans `import` est autorisée uniquement pour les symboles appartenant au **package courant**.
```text
saselang.compiler.lexer.Token
saselang.compiler.lexer::tokenize(...)
```
`.` qualifie le chemin ; `::` accède au symbole contenu.
Un symbole provenant d'une dépendance externe ne peut pas être référencé directement par un chemin complet dans une expression ou une déclaration. Il doit d'abord être importé explicitement avec une clause `from "vendor/package@requirement"`.
Cette règle évite d'introduire la syntaxe de coordonnées package (`/`, `@`, contraintes SemVer) dans la grammaire générale des expressions et garantit qu'un fichier énonce explicitement toutes ses provenances externes.
---

164
chapters/034-packages-identite-et-collisions-de-namespaces.md Normal file
View File

@@ -0,0 +1,164 @@
# 34. Packages, identité et collisions de namespaces
## 34.1 Identité indépendante du namespace — V1 REQUIS — FIGÉ
L'identité d'un package est indépendante de ses namespaces internes.
Identité canonique :
```text
vendor/package
```
Coordonnée exacte :
```text
vendor/package@version
```
Sélecteur de dépendance :
```text
vendor/package@requirement
```
Exemples :
```text
saselang/core@1.4.0
saselang/compiler-core@^0.8
acme/http-client@>=2.5,<3.0
sdl/sdl@3.1.*
```
Le `vendor/package` désigne l'identité logique. La version exacte ou l'exigence SemVer ne change jamais cette identité ; elle sélectionne une instance/résolution de cette identité.
Le namespace interne peut être totalement différent et ne doit pas être dérivé automatiquement de `vendor/package`.
## 34.2 Syntaxe des identifiants package — V1 REQUIS — FIGÉE EN PRINCIPE
Pour `vendor` et `package` :
```regex
[a-z][a-z0-9]*(?:-[a-z0-9]+)*
```
Règles :
- ASCII lowercase ;
- `-` sépare les mots à l'intérieur d'un composant ;
- `_` est interdit ;
- aucune conversion automatique `-` <-> `_` n'existe ;
- `/` sépare `vendor` et `package` ;
- `@` introduit une version exacte ou un requirement SemVer.
Cette convention doit fonctionner de manière identique dans les manifests, le resolver, le lockfile, les outils et la qualification `from` des imports.
## 34.3 Collision de namespaces — V1 REQUIS — FIGÉ
Deux packages peuvent légalement définir le même namespace et le même nom de symbole sans représenter le même type.
Par exemple, deux packages peuvent chacun fournir :
```text
namespace parser.ast;
public class Node
```
L'identité sémantique réelle d'un symbole inclut au minimum :
```text
instance de package résolue
+ namespace
+ symbole
```
Ainsi :
```text
acme/parser@2.4.1 :: parser.ast.Node
other/parser@5.0.0 :: parser.ast.Node
```
sont deux types distincts.
## 34.4 Qualification d'import par dépendance — V1 REQUIS — FIGÉ
Tout symbole provenant d'une dépendance externe doit être importé explicitement avec une clause `from` contenant son sélecteur canonique :
```text
from "vendor/package@requirement"
```
Direction syntaxique :
```text
import func some.namespace::function from "sdl/sdl@2.1.*" as sdlfun1;
import type some.namespace.Type from "acme/parser@^3.0" as ParserType;
```
La grammaire finale des différentes formes `import type|func|const|var` reste à harmoniser avec la grammaire lexicale complète, mais les règles sémantiques suivantes sont figées :
- `from` est **obligatoire** pour toute provenance extérieure au package courant ;
- le sélecteur `vendor/package@requirement` doit correspondre à un requirement effectivement déclaré dans le scope de dépendances applicable au fichier/package ;
- `from` ne déclenche jamais une résolution ad hoc ;
- le lockfile associe ce requirement à une version exacte résolue ;
- les dépendances transitives ne sont pas directement importables : un package qui utilise directement leur API doit les déclarer comme dépendances directes ;
- après l'import, le code utilise le nom local du symbole ou son alias ; la coordonnée package n'apparaît pas dans les expressions ordinaires.
Sans `from`, un `import` ne peut viser que le package courant.
L'alias `as` reste facultatif lorsque le nom local obtenu est unique dans le fichier. Il devient nécessaire lorsque plusieurs imports produiraient le même nom local ou lorsqu'un renommage explicite est souhaité.
## 34.5 Plusieurs versions directes d'une même identité — V1 REQUIS — FIGÉ EN PRINCIPE
Un même package consommateur peut déclarer plusieurs requirements directs pour le même `vendor/package` afin d'utiliser plusieurs lignées incompatibles en parallèle.
Exemple conceptuel :
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
Le code choisit explicitement l'instance souhaitée avec `from` :
```text
import func ... from "sdl/sdl@2.1.*" as sdlfun1;
import func ... from "sdl/sdl@^3.0" as sdlfun2;
```
Si les deux imports exposent le même nom terminal dans le même fichier, des alias locaux distincts sont obligatoires. La sélection de version ne peut pas être reportée à un chemin pleinement qualifié utilisé directement dans le corps du code.
Pour un même scope effectif de dépendances, deux requirements portant sur le même `vendor/package` doivent être **disjoints**.
Exemples autorisés :
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
Exemples interdits :
```text
sdl/sdl@>=1.0
sdl/sdl@^4.5
```
car les ensembles de versions acceptées se recouvrent.
De même :
```text
sdl/sdl@^3.0
sdl/sdl@3.1.*
```
est interdit puisque `3.1.*` appartient déjà à `^3.0`.
Le resolver doit détecter l'intersection SemVer des requirements avant résolution. Une intersection non vide est une erreur de manifest, même si une version particulière permettrait techniquement de satisfaire les deux requirements.
Cette règle supprime toute ambiguïté entre plusieurs slots directs de la même identité et rend `from "vendor/package@requirement"` déterministe.
Le graphe transitif peut lui aussi contenir plusieurs versions d'une même identité. Chaque instance résolue conserve une identité de type distincte lorsque les versions ne sont pas unifiées par le resolver.

334
chapters/035-manifests-et-workspaces.md Normal file
View File

@@ -0,0 +1,334 @@
# 35. Manifests et workspaces
## 35.1 Format et noms — V1 REQUIS — FIGÉ
Saselang V1 utilise **un seul format de manifest : TOML**. JSON ou d'autres formats alternatifs ne sont pas acceptés pour les manifests officiels afin de conserver une syntaxe unique pour le compilateur, le resolver et les outils.
Les noms canoniques sont :
```text
workspace.manifest.toml
project.manifest.toml
```
`workspace.manifest.toml` décrit uniquement un workspace. Il ne constitue jamais un package compilable.
`project.manifest.toml` est obligatoire à la racine de chaque projet/package, qu'il soit autonome ou membre d'un workspace.
Les deux manifests commencent par :
```toml
manifest-version = 1
```
`manifest-version` versionne le **format du manifest** ; il est distinct de la version SemVer du package.
## 35.2 Structure de `workspace.manifest.toml` — V1 REQUIS — FIGÉ
Structure V1 normative :
```toml
manifest-version = 1
[workspace]
projects-root = "projects"
members = [
"core",
"compiler",
"sdk",
]
[workspace.output]
build-root = "build"
temp-build-root = ".saselang/tmp"
[workspace.defaults.project]
vendor = "saselang"
version = "0.1.0"
license = "..."
authors = ["..."]
repository = "..."
[workspace.defaults.source]
root = "src"
[workspace.defaults.build]
profile = "dev"
target = "host"
[workspace.defaults.paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]
[workspace.dependencies."saselang/core@^1.0"]
source = "registry"
[workspace.dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"
[workspace.dependencies."local/tools@^1.0"]
source = "local"
path = "../shared/tools"
```
### 35.2.1 `[workspace]`
`projects-root` définit la racine à partir de laquelle les chemins de `members` sont résolus.
`members` contient la liste explicite des projets membres. Chaque membre doit contenir un `project.manifest.toml` valide.
V1 n'impose pas de découverte implicite récursive des projets ni de glob automatique. Ces mécanismes pourront être étudiés ultérieurement s'ils apportent un besoin concret.
### 35.2.2 `[workspace.output]`
Cette section configure les sorties du workspace :
```text
build-root
racine des sorties de build persistantes
temp-build-root
racine des fichiers temporaires/intermédiaires de build
```
Ces champs sont propres au workspace et ne sont pas des propriétés de package. Le toolchain doit empêcher les collisions entre plusieurs projets sous ces racines, notamment en séparant les sorties par projet, target et profil.
### 35.2.3 `[workspace.defaults.*]`
Seules les valeurs placées sous `workspace.defaults.*` sont **automatiquement héritables** par les projets membres.
Catégories V1 :
```text
workspace.defaults.project
workspace.defaults.source
workspace.defaults.build
workspace.defaults.paths
```
Un projet hérite d'une valeur absente de son propre manifest. S'il redéclare la même valeur, la valeur du projet la remplace.
Règles :
```text
scalaire absent dans le projet
-> valeur workspace héritée
scalaire présent dans le projet
-> remplacement
liste absente dans le projet
-> liste workspace héritée
liste présente dans le projet
-> remplacement complet de la liste
```
Pas de concaténation ou fusion implicite de listes.
Les tables sont des conteneurs de clés ; le remplacement s'effectue sur la valeur de chaque clé explicitement redéclarée, sauf les entrées de dépendances qui sont atomiques.
### 35.2.4 Chemins hérités
Un chemin défini dans `workspace.manifest.toml` est résolu relativement à la racine du workspace.
Un chemin défini ou redéfini dans `project.manifest.toml` est résolu relativement à la racine du projet.
L'héritage ne change jamais la base de résolution d'un chemin provenant du workspace.
### 35.2.5 `[workspace.dependencies]`
Cette section est un **catalogue de dépendances et de leurs moyens d'accès**. Une entrée du catalogue ne devient jamais automatiquement une dépendance de chaque projet.
Chaque clé utilise le sélecteur canonique :
```text
vendor/package@requirement
```
Les moyens d'accès prévus comprennent au minimum :
```text
workspace
local
git
registry
native
system
```
La syntaxe et les champs propres à chaque source sont finalisés dans la section dédiée aux types de dépendances.
Le futur registry officiel Saselang utilisera le même modèle `vendor/package@requirement` ; son protocole et son hébergement ne sont pas requis pour définir le langage V1.
## 35.3 Structure de `project.manifest.toml` — V1 REQUIS — FIGÉ
Structure V1 de base :
```toml
manifest-version = 1
[project]
vendor = "acme"
name = "my-application"
version = "1.2.0"
type = "bin"
description = "..."
license = "..."
authors = ["..."]
repository = "..."
[source]
root = "src"
[build]
profile = "dev"
target = "host"
[paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]
[dependencies]
"saselang/core@^1.0" = { workspace = true }
[build.dependencies]
[dev.dependencies]
[dev.unit.dependencies]
[dev.integration.dependencies]
[dev.environment.dependencies]
```
Les sections de features, artifacts et autres réglages spécialisés sont ajoutées dans leurs sections normatives respectives ; elles ne changent pas l'identité fondamentale du projet.
### 35.3.1 `[project]`
Après application de l'héritage du workspace, les valeurs effectives obligatoires sont :
```text
vendor
name
version
type
```
`name` et `type` doivent être déclarés par le projet lui-même. Ils ne sont pas héritables, car ils définissent son identité locale et sa nature.
`vendor` et `version` peuvent être hérités depuis `workspace.defaults.project` afin de supporter proprement les workspaces partageant un vendor ou une politique de version commune.
`version` est une version SemVer 2.0.0 exacte, jamais un requirement.
Métadonnées telles que :
```text
description
license
authors
repository
```
peuvent être héritées ou redéfinies. D'autres métadonnées de publication pourront être ajoutées seulement si elles ont une utilité concrète pour le toolchain/registry.
### 35.3.2 `[source]`
`root` indique le `source_root` du projet. La valeur V1 par défaut est :
```text
src
```
Elle peut provenir de `workspace.defaults.source.root`.
### 35.3.3 `[build]`
Cette section contient les paramètres de build propres au projet pouvant remplacer les defaults du workspace, notamment :
```text
profile
target
```
Les valeurs et la taxonomie exacte des targets sont définies dans la section targets. Les seuls profils V1 prévus sont `dev` et `release`, sous réserve de leur finalisation normative.
### 35.3.4 `[paths]`
Cette section peut remplacer les chemins hérités de `workspace.defaults.paths`.
Les catégories V1 prévues sont :
```text
dependencies
native-libraries
native-includes
```
Ces chemins servent à la résolution/recherche et ne deviennent jamais des identités de dépendance.
### 35.3.5 Sélection des dépendances du workspace
Un projet utilise explicitement une dépendance du catalogue workspace :
```toml
[dependencies]
"saselang/core@^1.0" = { workspace = true }
```
Le sélecteur doit correspondre à une entrée du catalogue visible du workspace.
Le projet peut aussi déclarer directement une dépendance et son moyen d'accès :
```toml
[dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"
```
Si le projet redéclare directement le même sélecteur qu'une définition workspace, la déclaration du projet remplace entièrement la définition workspace sélectionnée pour ce sélecteur. Il n'existe pas de fusion implicite de `source`, `url`, `path`, features, mappings natifs ou autres propriétés de dépendance.
## 35.4 Règles générales d'héritage — V1 REQUIS — FIGÉ
La précédence est :
```text
valeurs intrinsèques/defaults du langage/toolchain
< workspace.defaults.*
< project.manifest.toml
< options explicites de la commande de build lorsque l'option est conçue pour être overridable
```
Une option de ligne de commande ne peut pas changer l'identité `vendor/name@version` du projet pendant un build normal.
Les sections `workspace`, `workspace.output` et `workspace.dependencies` sont des structures du workspace ; elles ne sont pas copiées implicitement dans le projet.
## 35.5 Types de package V1 — V1 REQUIS — FIGÉ
Exactement un type par projet/package :
```text
lib
bin
```
Pas de combinaison `lib + bin` dans un même projet comme Cargo.
Si un produit a besoin d'une library, d'un CLI et d'un serveur, il utilise plusieurs projets/packages dans un workspace avec des dépendances explicites entre eux.
## 35.6 `browser-binary` — V1 RÉSERVÉ / FUTUR V3+
Type de projet/package envisagé pour l'environnement browser futur.
Direction possible :
- package d'entrée browser ;
- contient principalement/uniquement des `.saselscript` et ressources ;
- le code réutilisable est chargé via des dépendances `lib` ;
- produit ensuite des chunks/browser artifacts.
Cette conception est volontairement réservée et peut évoluer avant V3 sans changer les types V1 `lib` et `bin`.

111
chapters/036-semver-et-politique-de-releases.md Normal file
View File

@@ -0,0 +1,111 @@
# 36. SemVer et politique de releases
## 36.1 SemVer — V1 REQUIS — FIGÉ POUR L'ÉCOSYSTÈME
Les packages Saselang utilisent **Semantic Versioning 2.0.0 strict**.
```text
MAJOR.MINOR.PATCH
```
Les versions publiées, les contraintes de dépendances, le resolver et le lockfile doivent respecter SemVer 2.0.0. Saselang ne définit pas un ordre de versions concurrent à SemVer.
## 36.2 Discipline de compatibilité officielle — V1 REQUIS — FIGÉ EN PRINCIPE
Pour Core, SDK et packages officiels Saselang :
```text
MAJOR -> rupture de compatibilité publique
MINOR -> ajout rétrocompatible
PATCH -> correction rétrocompatible
```
Avant `1.0.0`, l'écosystème officiel peut imposer des règles plus strictes que le minimum SemVer afin de rendre l'évolution de Core/SDK plus prévisible.
Cette discipline est une norme de développement/publication de l'écosystème Saselang ; elle n'est pas une règle syntaxique du langage.
## 36.3 Stades officiels de prerelease — ÉCOSYSTÈME SASLANG — FIGÉ EN PRINCIPE
L'écosystème officiel utilise l'ordre conceptuel :
```text
pre -> alpha -> beta -> rc -> stable
```
Signification :
```text
pre développement/intégration active ; fonctionnalités incomplètes possibles
alpha ensemble cohérent et testable ; API encore susceptible d'évoluer
beta fonctionnalités prévues essentiellement complètes ; stabilisation
rc candidat à la release ; changements limités aux corrections nécessaires
stable aucun identifiant de prerelease
```
Pour que cet ordre soit également l'ordre de précédence **SemVer standard**, la forme canonique recommandée pour les packages officiels est :
```text
X.Y.Z-0.pre.N
X.Y.Z-1.alpha.N
X.Y.Z-2.beta.N
X.Y.Z-3.rc.N
X.Y.Z
```
Exemple :
```text
1.4.0-0.pre.3
1.4.0-1.alpha.1
1.4.0-2.beta.2
1.4.0-3.rc.1
1.4.0
```
Les nombres de prerelease SemVer ne comportent pas de zéros initiaux.
## 36.4 Fix de prerelease — ÉCOSYSTÈME SASLANG — FIGÉ EN PRINCIPE
Un correctif portant sur une `pre`, `alpha`, `beta` ou `rc` peut utiliser un composant `fix` supplémentaire :
```text
X.Y.Z-0.pre.N.fix.M
X.Y.Z-1.alpha.N.fix.M
X.Y.Z-2.beta.N.fix.M
X.Y.Z-3.rc.N.fix.M
```
Exemple :
```text
1.4.0-3.rc.2
1.4.0-3.rc.2.fix.1
1.4.0-3.rc.3
```
Une release stable n'utilise jamais `fix`. Une correction de :
```text
1.4.0
```
produit une nouvelle version PATCH, par exemple :
```text
1.4.1
```
La notation conceptuelle `-fix.NNN` n'est donc pas utilisée telle quelle si elle violerait ou perturberait les règles de SemVer strict ; `fix.M` fait partie de l'identifiant de prerelease et `M` n'a pas de zéros initiaux.
## 36.5 Build/documentation metadata — ÉCOSYSTÈME SASLANG — FIGÉ
`build` et `doc` ne sont pas des stades de prerelease.
SemVer fournit les métadonnées de build :
```text
X.Y.Z+build.N
X.Y.Z+doc.N
```
Elles ne modifient pas la précédence de version et ne constituent pas une nouvelle release de compatibilité.

330
chapters/037-dependances-et-scopes.md Normal file
View File

@@ -0,0 +1,330 @@
# 37. Dépendances et scopes
## 37.1 Deux axes indépendants — V1 REQUIS — FIGÉ
Une dépendance est décrite selon deux axes distincts :
```text
kind = nature logique de la dépendance
source = moyen utilisé pour la localiser/résoudre
```
V1 fixe au minimum les `kind` suivants :
```text
saselang
native
```
Les sources prévues par le schéma V1 sont :
```text
workspace
registry
local
git
artifact
system
```
Toutes les combinaisons ne sont pas nécessairement implémentées dès la première toolchain V1. Le schéma doit néanmoins permettre de les représenter sans refonte ultérieure.
Les dépendances npm/JVM/WASM et autres écosystèmes sont FUTUR V3+, mais doivent pouvoir être ajoutées comme nouveaux `kind`/modes de résolution sans changer l'identité canonique des dépendances.
## 37.2 Syntaxe unique des dépendances — V1 REQUIS — FIGÉE EN PRINCIPE
Tous les scopes et toutes les sources utilisent la même enveloppe TOML :
```toml
[dependencies."vendor/package@requirement"]
kind = "saselang"
source = "registry"
locator = "saselang"
```
Il n'existe pas en parallèle des raccourcis incompatibles de type :
```toml
foo = "^1.2"
foo = "../foo"
```
La clé canonique reste :
```text
vendor/package@requirement
```
`locator` désigne le moyen physique de retrouver la dépendance selon `source`. Sa sémantique exacte dépend de cette source, mais son rôle reste unique.
Exemples :
```toml
[dependencies."acme/math@^2.4"]
kind = "saselang"
source = "git"
locator = "https://example.org/acme/math.git"
```
```toml
[dependencies."acme/local-tools@^1.0"]
kind = "saselang"
source = "local"
locator = "../local-tools"
```
```toml
[dependencies."acme/parser@=1.4.2"]
kind = "saselang"
source = "artifact"
locator = "../libs/parser.saselib"
```
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```
## 37.3 Dépendance workspace — V1 REQUIS — FIGÉE EN PRINCIPE
Le workspace peut définir un catalogue :
```toml
[workspace.dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```
Un projet doit sélectionner explicitement l'entrée :
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "workspace"
```
Le `kind` doit correspondre à celui défini par le catalogue. Une entrée du catalogue n'est jamais injectée automatiquement dans tous les projets.
## 37.4 Scopes V1 — V1 REQUIS — FIGÉS
Les scopes requis en V1 sont :
```text
dependencies
build.dependencies
dev.dependencies
dev.unit.dependencies
dev.integration.dependencies
dev.environment.dependencies
```
Les scopes suivants sont réservés mais non normatifs tant que leurs workflows ne sont pas définis :
```text
dev.benchmark.dependencies
dev.documentation.dependencies
dev.example.dependencies
```
`dependencies` contient les dépendances du produit.
`build.dependencies` constitue un graphe de visibilité séparé destiné aux outils/hooks de build ; une build-dependency ne devient pas importable par le produit.
`dev.dependencies` est commun aux contextes de développement.
Les scopes `dev.unit`, `dev.integration` et `dev.environment` spécialisent respectivement les tests unitaires, les tests d'intégration et les environnements/outils externes de développement/test.
## 37.5 Héritage des scopes — V1 REQUIS — FIGÉ
```text
dev.unit effective =
dependencies
+ dev.dependencies
+ dev.unit.dependencies
```
Même règle pour `dev.integration` et `dev.environment`.
`build.dependencies` n'est pas ajouté à la visibilité des imports du produit ni des tests ; il appartient au graphe du système de build.
## 37.6 Remplacement entre scopes — V1 REQUIS — FIGÉ
L'unité de shadowing entre scopes est l'identité :
```text
vendor/package
```
Dès qu'un scope enfant déclare au moins une entrée pour cette identité, toutes les entrées héritées de cette même identité sont masquées dans ce scope.
Si plusieurs versions doivent réellement coexister dans le scope enfant, toutes leurs contraintes disjointes sont redéclarées explicitement dans ce scope.
Aucune fusion implicite champ par champ n'est effectuée.
## 37.7 Multi-version direct — V1 REQUIS — FIGÉ
Un même scope effectif peut contenir plusieurs selectors d'une même identité uniquement si leurs ensembles de versions sont deux à deux disjoints.
Valide :
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
Interdit :
```text
sdl/sdl@^3.0
sdl/sdl@3.1.*
```
Le resolver doit détecter les intersections de ranges et produire une erreur de manifest déterministe avant compilation.
## 37.8 Dépendance Saselang normale — V1 REQUIS — FIGÉ
Une dépendance de `kind = "saselang"` désigne toujours un package logique :
```text
vendor/package@requirement
```
L'artifact de bibliothèque Saselang consommé après résolution/build est une `.saselib`.
Une source `local` ou `git` désigne normalement les sources du package ; `artifact` peut désigner directement une `.saselib` précompilée.
## 37.9 Dépendances natives — V1 REQUIS — FIGÉ EN PRINCIPE
Une bibliothèque native est également encapsulée derrière :
```text
vendor/package@requirement
```
Par exemple :
```text
sdl/sdl@^3.0
```
peut représenter physiquement :
```text
Linux -> libSDL3.so / SONAME approprié
Windows -> SDL3.dll + import library éventuelle
macOS -> libSDL3.dylib ou framework approprié
```
Le nom physique n'est jamais l'identité logique de la dépendance.
Le même schéma de dépendance doit pouvoir porter des mappings conditionnés par target/platform/ABI/distribution. La syntaxe exacte du mapping natif sera finalisée avec la FFI et le linker, mais aucune nouvelle forme d'identité ne devra être introduite.
## 37.9.1 Variants natifs et sélection par environnement — V1 REQUIS — SQUELETTE FIGÉ
Une dépendance native possède une déclaration logique commune et peut ajouter une liste homogène de `variants` lorsque sa représentation physique dépend de l'environnement.
Exemple conceptuel :
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
[[dependencies."sdl/sdl@^3.0".variants]]
platform = "linux"
library = "SDL3"
[[dependencies."sdl/sdl@^3.0".variants]]
platform = "windows"
library = "SDL3"
```
Un variant peut contraindre une combinaison des dimensions suivantes :
```text
target-family
platform
architecture
abi
distribution
distribution-version
capabilities
```
Les variants n'introduisent jamais une nouvelle identité de dépendance : l'identité logique reste `vendor/package@requirement`.
Un variant plus spécifique prévaut sur un variant strictement moins spécifique lorsque les deux correspondent. Si plusieurs variants applicables sont incomparables en spécificité et qu'aucun n'est l'unique meilleur candidat, le manifest est ambigu et la toolchain doit produire une erreur déterministe. L'ordre textuel des variants ne départage jamais un conflit.
Exemple d'ambiguïté à refuser pour un target Linux x86_64 GNU :
```text
variant A : platform=linux, architecture=x86_64
variant B : platform=linux, abi=gnu
```
Aucun des deux n'est strictement plus spécifique que l'autre.
Le noyau V1 des propriétés physiques peut comprendre :
```text
library
linkage = auto | static | shared
deployment = auto | external | bundled
search-paths
include-paths
```
Le modèle réserve sans obligation d'implémentation complète en V1 :
```text
runtime-files
link-files/import-libraries
frameworks
system-packages
resources
plugins
```
Une dépendance native représente donc un package natif logique pouvant comporter plusieurs composants physiques ; elle n'est jamais réduite au modèle « une dépendance = un unique fichier .so/.dll ».
## 37.10 Requirements SemVer — V1 REQUIS — FIGÉ
Les versions suivent strictement SemVer 2.0.0.
Les requirements V1 doivent au minimum pouvoir exprimer :
```text
=1.4.7
^4.5
~1.4.2
3.1.*
>=1.0
>=1.2,<2.0
```
Une version exacte canonique comporte toujours `MAJOR.MINOR.PATCH`.
Une forme abrégée telle que `2.1` ne peut être acceptée que comme requirement/range dont la signification est définie sans ambiguïté ; elle n'est jamais une version exacte SemVer incomplète.
## 37.11 Imports de dépendances — V1 REQUIS — FIGÉ EN PRINCIPE
Toute utilisation d'un symbole provenant d'une dépendance externe au package courant passe par un import explicite :
```text
import type namespace.Type
from "vendor/package@requirement"
as LocalType;
```
Même principe pour `func`, `const` et `var`.
`as` est facultatif tant que le nom local est unique ; il devient obligatoire en cas de collision locale.
Le `from` doit référencer un selector effectivement déclaré dans le graphe effectif du fichier. Il ne déclenche aucune résolution indépendante.
La qualification complète sans import reste limitée aux symboles du package courant.

166
chapters/038-resolver-et-lockfile.md Normal file
View File

@@ -0,0 +1,166 @@
# 38. Resolver et lockfile
## 38.1 Modèle de résolution — V1 REQUIS — FIGÉ
Trois notions sont distinguées :
```text
identity vendor/package
selector vendor/package@requirement
resolved instance vendor/package@MAJOR.MINOR.PATCH
```
Le manifest et les imports `from` utilisent le selector. Le compilateur/linker consomme finalement des instances exactes.
## 38.2 Déduplication transitive — V1 REQUIS — FIGÉE
Deux dépendances transitives peuvent demander des ranges qui se chevauchent.
Si une même version exacte satisfait toutes les contraintes regroupables, le resolver doit préférer une instance commune.
Exemple :
```text
A -> foo/bar@^2.0
B -> foo/bar@^2.5
```
peut être résolu par une seule instance `foo/bar@2.x` compatible.
Si les contraintes ne peuvent pas être satisfaites par une instance commune, plusieurs versions exactes peuvent coexister :
```text
A -> foo/bar@^2.0
B -> foo/bar@^3.0
```
La politique normative privilégie :
```text
1. conservation des versions déjà verrouillées lorsqu'elles restent valides ;
2. minimisation du nombre d'instances distinctes ;
3. versions SemVer compatibles les plus élevées lorsqu'une nouvelle résolution est nécessaire.
```
L'algorithme interne exact du resolver n'est pas imposé par la Bible ; seul le résultat déterministe est normatif.
## 38.3 Prereleases — V1 REQUIS — FIGÉ
Un requirement stable ne sélectionne pas implicitement une prerelease.
Une prerelease doit être explicitement autorisée par le requirement conformément aux règles SemVer.
## 38.4 Sources et unicité du contenu — V1 REQUIS — FIGÉ
Une coordonnée exacte :
```text
vendor/package@1.2.3
```
ne doit pas désigner simultanément deux contenus/sources différents dans une même résolution.
Un remplacement explicite de source est possible via le manifest, mais après application du remplacement il ne reste qu'une source effective pour l'instance exacte.
## 38.5 Lockfile — V1 REQUIS — FIGÉ
Le lockfile est :
```text
saselang.lock
```
Il est consulté à chaque build.
Il n'est réécrit que si la résolution effective change ou doit être complétée ; un build ordinaire n'effectue pas d'upgrade opportuniste lorsqu'une version verrouillée reste compatible.
Le premier build sans lockfile peut le générer.
## 38.6 Racine de résolution — V1 REQUIS — FIGÉE
Package autonome :
```text
project.manifest.toml
saselang.lock
```
Workspace :
```text
workspace.manifest.toml
saselang.lock
projects/.../project.manifest.toml
```
Lorsqu'un projet est construit comme membre d'un workspace, le lockfile du workspace fait autorité.
## 38.7 Contenu minimal du lock — V1 REQUIS — FIGÉ EN PRINCIPE
Le lock enregistre au minimum :
```text
identité vendor/package
selector/requirement d'origine
version exacte résolue
kind
source exacte
locator stable lorsque pertinent
checksum/intégrité lorsque pertinent
commit exact pour Git
features résolues
instances multi-version
graphe de dépendances
conditions target/features pertinentes
```
Le lock ne doit pas enregistrer comme identité portable un chemin absolu découvert vers une bibliothèque système telle que `/usr/lib/...`.
## 38.8 Modes de résolution — V1 REQUIS — FIGÉS EN PRINCIPE
La toolchain doit fournir conceptuellement trois comportements :
```text
normal
utilise le lock ;
le complète/corrige si nécessaire ;
n'upgrade pas gratuitement
locked
interdit toute modification du lock ;
échoue si le graphe demandé n'est pas reproductible
update
recherche volontairement de nouvelles versions compatibles
```
Les noms CLI exacts sont à définir avec l'outillage.
## 38.9 Intégrité — V1 REQUIS — FIGÉE EN PRINCIPE
Les sources téléchargées contrôlées par Saselang (`registry`, `artifact`, archives distantes futures) doivent être verrouillées par checksum cryptographique.
Git doit être verrouillé sur un commit exact.
Les sources locales ne nécessitent pas de checksum dans le lockfile.
Les bibliothèques `system`/`native` peuvent être découvertes localement sans inscrire leur chemin absolu dans le lock.
## 38.10 Identité nominale des symboles externes — V1 REQUIS — FIGÉE
L'identité nominale interne d'un symbole externe inclut l'instance de package résolue :
```text
resolved-package-instance
+ namespace
+ symbol
```
Ainsi :
```text
acme/foo@1.0.0 :: data.Node
acme/foo@2.0.0 :: data.Node
```
sont deux types distincts, même s'ils possèdent la même représentation structurelle.

140
chapters/039-features-module-saselmod-et-compilation-conditionnelle.md Normal file
View File

@@ -0,0 +1,140 @@
# 39. Features, `module.saselmod` et compilation conditionnelle
## 39.1 Features — V1 REQUIS — FIGÉES EN PRINCIPE
Une feature est une capacité optionnelle déclarée par un package.
Elle peut notamment :
```text
activer une dépendance optionnelle
activer un module
sélectionner une capacité/backend fonctionnel de library
contraindre d'autres features
```
Une feature ne représente jamais une plateforme/architecture à la place du modèle de target.
## 39.2 Contraintes de features — V1 REQUIS — FIGÉES EN PRINCIPE
V1 doit pouvoir exprimer au minimum :
```text
requires
conflicts
one-of
at-least-one
```
`all-of` est redondant avec plusieurs `requires` et n'est pas requis comme primitive distincte.
`provides`/`replaces` ne sont pas introduits sans besoin concret démontré.
Les groupes et contraintes globales appartiennent au manifest du package.
## 39.3 Dépendances optionnelles — V1 REQUIS — FIGÉES EN PRINCIPE
Une feature peut activer une dépendance déjà déclarée comme optionnelle dans le manifest. La dépendance garde une définition unique ; la feature ne duplique pas sa source, version ou son mapping.
Les features demandées à une dépendance doivent être déclarables dans l'entrée de dépendance correspondante.
La suppression/renommage d'une feature publique d'un package peut constituer une rupture de compatibilité SemVer.
## 39.4 `module.saselmod` — V1 REQUIS — FIGÉ EN PRINCIPE
`module.saselmod` reste totalement optionnel.
S'il existe, sa première déclaration après éventuel en-tête/documentation est obligatoirement :
```text
namespace ...;
```
et doit correspondre au chemin du module relativement au `source_root`.
Il ne contient ni exports, ni réexports, ni dépendances de package, ni configuration générale de build.
Il peut porter des propriétés réellement module-wide, notamment :
```text
doc ...
deprecated ...
forbid unsafe
requires feature ...
requires capability ...
requires target ...
```
La syntaxe finale de ces directives reste à figer.
## 39.5 Héritage des politiques de module — V1 REQUIS — FIGÉ EN PRINCIPE
Les contraintes/politiques structurelles telles que :
```text
forbid unsafe
requires feature
requires capability
requires target
```
sont héritées par les sous-modules, sauf règle future explicitement plus restrictive.
`doc` n'est pas hérité.
`deprecated` ne constitue pas une copie automatique du texte de dépréciation dans tous les sous-modules ; l'utilisation d'un chemin passant par un module déprécié doit néanmoins pouvoir produire le diagnostic approprié.
## 39.6 `compile if` — V1 REQUIS — SQUELETTE FIGÉ, SYNTAXE À FINALISER
Saselang V1 conserve une compilation conditionnelle structurelle intégrée au parser/AST.
Ce n'est jamais un préprocesseur textuel.
Le `compile if` :
```text
ne produit jamais de valeur ;
ne peut jamais être utilisé comme expression ;
ne peut dépendre que d'informations déterminables à la compilation.
```
En V1 il peut sélectionner :
```text
des déclarations top-level complètes ;
des blocs d'implémentation dans le corps d'une callable.
```
Il ne doit pas servir à modifier conditionnellement les champs/membres structurels internes d'un type déjà déclaré.
Le bloc non sélectionné est éliminé avant HIR/Sase IR. Il doit néanmoins être suffisamment lexé/parsé pour rester syntaxiquement valide.
La syntaxe exacte (`compile if (...)`, forme de `else`, etc.) reste à finaliser.
## 39.7 Environnement de compilation — V1 REQUIS — SQUELETTE FIGÉ
Le compilateur/Core doit pouvoir exposer dans les contextes de compilation conditionnelle des informations déterministes telles que :
```text
language version
compiler version
Core/SDK version
package identity/version
features actives
dépendances résolues
profile
artifact
target family
platform
architecture
ABI
endianness
pointer width
capabilities
```
Les informations doivent être typées lorsque possible.
Le code applicatif normal n'obtient pas pour autant un accès arbitraire au filesystem, au réseau ou aux variables d'environnement pendant l'évaluation de `compile if`.
Les chemins workspace/package/build sont réservés aux outils de build lorsqu'ils sont réellement nécessaires et ne deviennent pas une dépendance sémantique portable du programme.

208
chapters/040-targets-plateformes-architectures-abi-distributions-et-capabilities.md Normal file
View File

@@ -0,0 +1,208 @@
# 40. Targets, plateformes, architectures, ABI, distributions et capabilities
## 40.1 Dimensions orthogonales — V1 REQUIS — FIGÉES
La Bible distingue explicitement :
```text
TargetFamily
Platform
Architecture
ABI
Distribution
Capability
Feature
ArtifactKind
ExportFormat
```
Ces dimensions ne doivent pas être fusionnées dans une chaîne opaque ni confondues entre elles.
Une cible de compilation concrète est décrite par la combinaison des dimensions pertinentes.
## 40.2 Représentation Core des domaines — V1 REQUIS — FIGÉE EN PRINCIPE
Le choix entre `enum` et type d'identifiant extensible dépend de la nature sémantique du domaine, et non d'une tentative de protéger artificiellement V1/V2 contre toute évolution.
Les domaines naturellement fermés pour une version donnée peuvent être des `enum` Core, par exemple :
```text
Endianness
PackageType
Linkage
Deployment
```
Une valeur peut être ajoutée ou une représentation corrigée pendant V1/V2 si un besoin réel apparaît. Ces générations étant internes, un tel changement peut nécessiter l'adaptation simultanée du compilateur, du Core, du SDK et des outils.
Les domaines intrinsèquement ouverts ou liés à l'écosystème externe sont de meilleurs candidats à des types d'identifiants compiler/Core-known extensibles, notamment :
```text
Platform
Architecture
ABI
Distribution
Capability
ArtifactKind
ExportFormat
```
`TargetFamily` peut être un `enum` ou un identifiant extensible selon la forme finale retenue pendant l'implémentation V1 ; cette décision ne doit pas modifier le modèle du manifest.
Exemples de valeurs compiler-known :
```text
Platform::Linux
Platform::Windows
Architecture::X86_64
Architecture::AArch64
ABI::Gnu
Distribution::Debian
Capability::FileSystem
ArtifactKind::NativeExecutable
```
La représentation binaire/interne exacte de ces types reste une décision du Core/toolchain V1. Avant la première baseline publique V3+, la priorité est la cohérence sémantique et l'absence de verrou architectural inutile.
## 40.3 Target families — V1 REQUIS / RÉSERVÉ
V1 doit réellement supporter le chemin LLVM pour au minimum :
```text
Native
Embedded
```
Les familles suivantes doivent être réservables sans refonte du modèle :
```text
Browser
Wasm
Jvm
JavaScript
```
D'autres familles futures pourront être ajoutées sans changer la forme du manifest.
L'interpréteur V1 est un moteur d'exécution Saselang et n'est pas confondu avec une `TargetFamily` machine.
## 40.4 Platforms — V1 REQUIS / RÉSERVÉ
Le modèle doit pouvoir représenter notamment :
```text
Linux
Windows
MacOS
FreeBSD
Android
iOS
None
```
`None` représente une cible sans OS, notamment bare-metal/embedded.
La liste n'est pas fermée.
## 40.5 Architectures — V1 REQUIS / RÉSERVÉ
Le modèle doit au minimum être capable de représenter les grandes familles que LLVM peut cibler, notamment :
```text
X86
X86_64
Arm
AArch64
RiscV32
RiscV64
Wasm32
```
La liste exacte officiellement validée par Saselang V1 dépend de la toolchain LLVM/runtime/sysroot disponibles ; le modèle ne doit pas l'empêcher d'évoluer.
## 40.6 ABI — V1 REQUIS / RÉSERVÉ
Le modèle doit pouvoir représenter notamment :
```text
Gnu
Musl
Msvc
Darwin
Eabi
Eabihf
None
```
Saselang peut utiliser les triples LLVM en interne, mais le triple LLVM brut n'est pas la seule abstraction publique du target.
## 40.7 Distribution — V1 RÉSERVÉ / FUTUR V3+
`Distribution` est distincte de `Platform` et de l'ABI.
Elle doit pouvoir représenter à terme des familles telles que :
```text
Debian
Ubuntu
Rhel
Fedora
Arch
Alpine
```
ainsi que leur version lorsque pertinente.
Cette dimension sert principalement à :
```text
résoudre/découvrir des dépendances système ;
exprimer des contraintes d'environnement de distribution ;
produire des packages/export formats spécifiques.
```
Elle n'est pas requise pour toute compilation native V1.
## 40.8 Capabilities — V1 REQUIS — SQUELETTE FIGÉ
Les capabilities décrivent des capacités réelles de l'environnement et non des options libres du package.
V1 doit pouvoir représenter au minimum :
```text
Heap
FileSystem
Environment
Process
Threads
Network
Sockets
Clock
DynamicLoading
SharedMemory
StandardInput
StandardOutput
StandardError
```
Le modèle doit aussi permettre de décrire les capacités atomiques pertinentes sans supposer qu'elles sont identiques sur tous les targets.
Une capability statique signifie que l'environnement fournit la capacité ; elle ne garantit pas qu'une opération runtime particulière réussira.
## 40.9 Compatibilité target/dépendance — V1 REQUIS — FIGÉE EN PRINCIPE
Un package ou une dépendance peut déclarer des contraintes de target/platform/ABI/capabilities.
Le resolver/build doit détecter les incompatibilités avant la compilation effective lorsqu'elles sont déterminables.
Une dépendance native peut fournir des mappings distincts selon :
```text
TargetFamily
Platform
Architecture
ABI
Distribution
```
sans changer son identité logique `vendor/package@requirement`.

475
chapters/041-artifacts-exports-profils-et-reservation-des-formats-futurs.md Normal file
View File

@@ -0,0 +1,475 @@
# 41. Artifacts, exports, profils et réservation des formats futurs
## 41.1 Type de package vs artifact — V1 REQUIS — FIGÉ
Le type du package reste strictement :
```text
lib
bin
```
Un package ne combine pas les deux rôles.
`browser-binary` est réservé comme troisième type possible FUTUR V3+, sans obligation d'implémentation V1.
## 41.2 Artifacts V1 d'un package `lib` — V1 REQUIS — FIGÉS EN PRINCIPE
Les artifacts fondamentaux V1 sont :
```text
Saselib
NativeStatic
NativeShared
```
`Saselib` est l'artifact canonique de dépendance Saselang.
Les formats physiques de `NativeStatic`/`NativeShared` dépendent de la plateforme et ne deviennent pas de nouveaux types d'artifact (`.a`, `.lib`, `.so`, `.dll`, `.dylib`, etc.).
## 41.3 Artifacts V1 d'un package `bin` — V1 REQUIS — FIGÉ EN PRINCIPE
L'artifact fondamental V1 est :
```text
NativeExecutable
```
Les sorties techniques du backend :
```text
LLVM IR
object
assembly
```
sont des `emit`/outputs techniques et non des types de package ni nécessairement des artifacts publiables de premier rang.
## 41.4 `.saselib` — V1 REQUIS — DIRECTION FIGÉE
Une `.saselib` doit être aussi target-neutral que possible et transporter les informations nécessaires à la consommation/recompilation finale, notamment :
```text
identité vendor/package
version exacte
version de format saselib
API publique
métadonnées de types/generics nécessaires
Sase IR ou représentation compilable équivalente
dépendances requises
features pertinentes
contraintes de target/capability lorsque nécessaires
intégrité/métadonnées
```
Le format physique V1 est fixé :
```text
TAR POSIX/PAX
compressé par Zstandard
extension publique .saselib
```
La première entrée du flux TAR est obligatoirement :
```text
META-INF/saselib.manifest.toml
```
L'ordre des autres entrées et le niveau Zstandard canonique seront déterminés plus tard par benchmark, sans modifier le modèle logique ni l'extension `.saselib`.
Les portions dépendantes d'une ABI/FFI native peuvent réduire la portabilité de la `.saselib` sans changer son rôle logique.
## 41.5 Mode de distribution d'exécutable — V1 REQUIS — FIGÉ EN PRINCIPE
Pour `NativeExecutable`, V1 prévoit au minimum :
```text
external
standalone
```
`standalone` signifie que la toolchain inclut ou accompagne tout ce qui peut raisonnablement et légalement être rendu autonome : runtime Saselang, libraries statiquement intégrables et ressources nécessaires.
Il ne promet pas l'absence absolue de tout prérequis système lorsque cela est impossible.
Le mode n'est pas un type de package.
## 41.6 Export formats — V1 RÉSERVÉ / FUTUR
Les formats :
```text
zip
tar
tar.gz
tar.zst
```
sont des formats d'export/distribution, pas des artifacts fondamentaux.
Le modèle doit également pouvoir accueillir à terme :
```text
deb
rpm
apk
AppImage
.run
msi
pkg
dmg
jar
browser chunks
Android packages
iOS packages
```
sans modifier les notions `PackageType`, `ArtifactKind` ou `TargetFamily` existantes.
## 41.7 Séparation artifact / distribution / export — V1 REQUIS — FIGÉE
Exemple conceptuel :
```text
package type = bin
artifact = NativeExecutable
target family = Native
platform = Linux
architecture = X86_64
ABI = Gnu
distribution = Debian (optionnel/réservé)
export format = Deb (futur)
```
Chaque axe répond à une question différente et ne doit pas être réencodé dans le nom d'un autre axe.
## 41.8 Profils V1 — V1 REQUIS — FIGÉ
Les seuls profils standards V1 sont :
```text
dev
release
```
Un profil décrit **comment compiler**. Il ne décrit ni l'action exécutée, ni le scope de dépendances actif, ni une variante sémantique du langage.
La V1 n'introduit pas de profils standards distincts `test`, `benchmark`, `documentation`, `integration`, etc. Ces notions relèvent des commandes, des scopes de dépendances ou d'outils spécialisés. Les profils nommés supplémentaires restent une possibilité future, mais ne doivent pas être nécessaires à l'architecture V1.
### 41.8.1 Propriétés génériques d'un profil
Les propriétés communes V1 sont limitées à des réglages indépendants du backend :
```text
optimization
debug-info
incremental
```
`optimization` utilise un domaine sémantique et non des niveaux propres à LLVM :
```text
none
low
balanced
speed
size
```
`debug-info` utilise :
```text
none
line
full
```
`incremental` est booléen.
Exemple :
```toml
[profiles.dev]
optimization = "none"
debug-info = "full"
incremental = true
[profiles.release]
optimization = "speed"
debug-info = "line"
incremental = false
```
Les defaults normatifs V1 sont ceux de cet exemple.
Le mapping d'un niveau générique vers les options concrètes du backend appartient à l'implémentation du backend, mais deux backends conformes ne doivent pas modifier la sémantique observable de Saselang pour interpréter différemment un profil.
### 41.8.2 Ce qu'un profil ne peut jamais modifier
Un profil ne peut notamment pas :
```text
désactiver les contrôles d'overflow définis par Saselang
modifier la sémantique d'un index hors limites
modifier l'ordre d'évaluation
modifier la représentation sémantique des types
changer les règles Result/throws
désactiver les vérifications de sûreté du langage
faire varier la validité d'un programme Saselang autrement que par une limite propre au backend/target
```
`dev` et `release` doivent donc compiler le **même programme Saselang** ; seuls le coût de compilation, l'optimisation, les informations de debug et les caractéristiques non sémantiques de l'artifact peuvent varier.
### 41.8.3 Options propres au backend
Les options non portables vivent dans un sous-espace explicitement backend-specific :
```toml
[profiles.release.backend.llvm]
lto = "thin"
```
La V1 réserve cette structure générale :
```text
profiles.<profile>.backend.<backend>
```
sans faire des options LLVM des propriétés universelles du manifest.
Pour LLVM V1, le réglage `lto` peut prendre :
```text
off
thin
full
```
Les options backend supplémentaires ne doivent être ajoutées que lorsqu'un besoin réel existe.
Le choix de CPU, d'architecture, d'ABI ou de plateforme n'est pas une propriété du profil ; il appartient au target.
### 41.8.4 Sélection du profil
Les commandes de build utilisent `dev` par défaut, sauf demande explicite contraire.
Une commande peut sélectionner :
```text
--profile dev
--profile release
```
Un raccourci CLI `--release` peut exister comme équivalent strict de `--profile release`, mais il ne constitue pas un troisième mécanisme de configuration.
## 41.9 Principe de réservation V1 — V1 REQUIS — FIGÉ
La Bible V1 doit définir les **dimensions stables** nécessaires aux évolutions prévues, même lorsque la première toolchain n'implémente pas toutes leurs valeurs.
La V1 n'est pas tenue d'implémenter :
```text
browser runtime définitif
WASM/JVM/JS backends
packaging Android/iOS
.deb/.rpm/.apk/.msi/.dmg
installation automatique de dépendances système sur toutes les distributions
```
mais elle ne doit pas imposer un modèle de manifest, de target ou d'artifact qui obligerait à refaire ces abstractions en V3+.
## 41.9.1 Format physique `.saselib` V1 — V1 REQUIS — FIGÉ
L'artefact canonique d'un package Saselang de type `lib` est :
```text
<name>.saselib
```
Pour la version de format V1, une `.saselib` est physiquement :
```text
archive TAR POSIX/PAX
compressée par Zstandard
```
Le choix du conteneur et de la compression est un détail interne du format `.saselib` ; l'extension publique reste toujours `.saselib`.
La structure physique du format V1 impose que la première entrée du flux TAR soit :
```text
META-INF/saselib.manifest.toml
```
Cette entrée est obligatoire et doit permettre au toolchain de connaître immédiatement au moins :
```text
version du format saselib
identité vendor/package
version exacte SemVer du package
compatibilité de version du langage Saselang
nature/portabilité de la bibliothèque
inventaire logique des contenus présents
requirements de dépendances
features pertinentes
contraintes de target/capabilities
métadonnées FFI/native nécessaires
informations d'intégrité prévues par la version de format
```
Le format interne est extensible et versionné. Les autres contenus possibles peuvent inclure notamment :
```text
Sase IR
métadonnées publiques/types/generics
artifacts binaires spécifiques à certains targets
ressources
documentation
autres données définies par une version future du format
```
Leur présence dépend du `format-version` et de ce qui est déclaré dans `META-INF/saselib.manifest.toml`.
L'ordre exact des entrées après `META-INF/saselib.manifest.toml` n'est **pas encore normatif**. Il sera défini plus tard en fonction des besoins réels de chargement, de streaming, de cache et des benchmarks du toolchain.
Le format V1 ne dépend d'aucun format propriétaire :
```text
TAR POSIX/PAX
Zstandard
```
sont des formats ouverts et documentés.
La compression est appliquée au flux TAR complet, afin de favoriser à la fois :
```text
bon ratio de compression
décompression rapide
chargement séquentiel efficace par les outils
```
Le niveau Zstandard canonique n'est pas fixé par la Bible à ce stade. Il devra être déterminé par benchmark sur de vraies `.saselib`.
Une future version de format `.saselib` pourra changer son conteneur ou sa stratégie de compression si un autre format ouvert apporte un avantage démontré, sans changer l'extension ni le modèle logique Saselang.
## 41.10 Pilotage du build et commandes V1 — V1 REQUIS — FIGÉ EN SQUELETTE
La toolchain V1 conserve les noms d'outils dédiés :
```text
saselc
saseldoc
```
La V1 n'introduit pas un troisième outil générique uniquement pour masquer ces responsabilités.
### 41.10.1 Commandes minimales de `saselc`
Le squelette de commandes V1 est :
```text
saselc check
saselc build
saselc run
saselc test
saselc clean
saselc fetch
saselc update
```
Leur rôle est distinct :
```text
check
résolution du projet et des dépendances nécessaires
parsing, analyse sémantique et validations
pas de génération de l'artifact final
build
compilation et génération de l'artifact demandé
run
réservé à un projet de type bin
build si nécessaire puis exécution
transmet explicitement les arguments du programme
test
découverte/compilation/exécution des tests selon les règles V1
utilise les scopes dev appropriés
clean
supprime les sorties de build et temporary build de la racine concernée
ne supprime ni manifest ni lockfile
ne purge pas implicitement les caches globaux de dépendances
fetch
résout et récupère les dépendances nécessaires sans construire l'artifact
utilise le lock existant et le complète seulement si nécessaire
update
demande explicitement une nouvelle résolution compatible avec les requirements
met à jour le lockfile
peut cibler tout le graphe ou un selector/une identité précise
```
`build` n'effectue pas d'upgrade opportuniste lorsqu'une version verrouillée reste valide.
### 41.10.2 Emits techniques
Les sorties techniques ne deviennent pas des commandes ni des types de package supplémentaires.
`build` peut demander un ou plusieurs emits, par exemple conceptuellement :
```text
Sase IR
LLVM IR
object
assembly
```
La syntaxe CLI exacte peut prendre la forme d'une option `--emit`, à normaliser avec la CLI finale.
### 41.10.3 Racine de résolution
Lorsqu'elle est exécutée depuis un projet autonome, la toolchain utilise :
```text
project.manifest.toml
saselang.lock.toml
```
à la racine de résolution du projet.
Dans un workspace, `workspace.manifest.toml` et le lockfile de la racine workspace font autorité pour les projets membres construits dans ce contexte.
La CLI doit permettre de désigner explicitement un manifest/racine lorsqu'une découverte automatique ne convient pas. Le nom exact de cette option est à normaliser avec la grammaire CLI finale, sans changer le modèle de résolution.
### 41.10.4 Build de workspace et sélection de projet
Un appel de `saselc` depuis une racine workspace peut viser l'ensemble des membres compatibles avec la commande ou un membre explicite.
La sélection d'un projet doit utiliser son identité de package et non un nom de dossier ambigu.
La syntaxe exacte de sélection CLI reste à normaliser, mais cette capacité est requise par l'architecture workspace V1.
### 41.10.5 `saseldoc`
`saseldoc` est l'unique outil officiel de génération et validation de documentation Saselang. Il ne doit pas exister plusieurs générateurs officiels séparés selon la visibilité ou le format.
Le même outil reçoit des paramètres permettant au minimum de sélectionner :
```text
visibilités incluses
format de sortie
chemin de sortie
base path / base URL lorsque le format le nécessite, notamment HTML
projet/package/workspace ciblé
```
La grammaire CLI exacte reste à finaliser, mais ces dimensions appartiennent à la même commande/outillage `saseldoc`.
`saseldoc` utilise les mêmes règles de résolution de package, workspace, dépendances et visibilité que le compilateur. Il ne constitue pas un profil de build.
---

27
chapters/042-main-et-exitcode.md Normal file
View File

@@ -0,0 +1,27 @@
# 42. `main` et `ExitCode`
## 42.1 `main` — V1 REQUIS — FIGÉ
Dans `main.saselrun` :
```text
func main(Array<String> args) -> Result<ExitCode>
```
Pas de visibilité explicite.
`main` ne peut pas déclarer `throws`, même s'il retourne `Result`.
L'environnement top-level ne possède pas d'appelant Saselang capable de l'envelopper dans un `try/catch`.
## 42.2 `ExitCode` — V1 REQUIS — FIGÉ EN PRINCIPE
`ExitCode` est un type Core à sémantique portable.
Sa représentation ABI peut dépendre de la plateforme, mais sa signification Saselang reste stable.
Une erreur de `main` doit produire au minimum une représentation utilisateur raisonnable et un code d'échec.
Logging/tracing reste une API séparée.
---

145
chapters/043-documentation-et-tests-de-conformite.md Normal file
View File

@@ -0,0 +1,145 @@
# 43. Documentation et tests de conformité
## 43.1 Bible multifichier — V1 REQUIS — FIGÉ EN PRINCIPE
La Bible doit être suffisamment complète pour implémenter V1.
Les sections futures ne doivent pas masquer les trous normatifs V1.
À partir de `0.2.12`, la distribution documentaire de référence devient multifichier. Une archive complète contient au minimum :
```text
README
sommaire
un fichier Markdown par chapitre
un fichier compagnon examples + DO/DON'T par chapitre
annexes référencées
manifest de distribution
```
Le découpage physique ne change pas la portée normative d'une règle.
## 43.2 Archives complètes et deltas SemVer — V1 REQUIS — FIGÉ EN PRINCIPE
Une version de baseline est distribuée sous forme d'archive complète `full`.
Les versions suivantes peuvent être distribuées sous forme de `delta` contenant uniquement les fichiers ajoutés, modifiés ou supprimés par rapport à une version de base explicitement déclarée.
Le manifest d'un delta doit notamment identifier :
```text
version cible
version de base
fichiers ajoutés
fichiers modifiés
fichiers supprimés
hashes des fichiers livrés
```
Un delta ne doit pas contenir des fichiers inchangés uniquement pour reconstruire artificiellement une archive complète.
Une archive complète peut être régénérée périodiquement ou lors d'un changement structurel majeur.
## 43.3 Examples / DO-DON'T — V1 REQUIS — DIRECTION FIGÉE
Chaque chapitre possède un fichier compagnon destiné à transformer progressivement les règles en :
```text
DO
DON'T
WHY
compiler error
edge cases
```
Durant la phase `0.x`, la couverture de ces fichiers peut rester incomplète lorsque le chapitre lui-même contient encore les exemples historiques nécessaires à la compréhension. Avant la stabilisation V1, les exemples normatifs doivent être consolidés et une partie doit devenir des tests de conformité de la toolchain.
## 43.4 Commentaires ordinaires — V1 REQUIS — FIGÉ
Commentaires non documentaires :
```text
// commentaire de ligne
/* commentaire de bloc */
```
Les commentaires de bloc sont imbriquables. Les commentaires ordinaires peuvent apparaître dans l'implémentation, y compris dans les corps exécutables. Leur contenu peut être Unicode.
## 43.5 Saseldoc source — V1 REQUIS — FIGÉ
Les commentaires documentaires sont :
```text
/// documentation de ligne
/** documentation de bloc */
```
Ils ont la même sémantique documentaire avec deux ergonomies d'écriture différentes. Saselang ne reprend pas la redondance Javadoc/PHPDoc consistant à dupliquer systématiquement la signature via `@param`, `@return` ou `@throws` ; `saseldoc` dérive ces informations du programme.
Une Saseldoc est autorisée uniquement lorsqu'elle est immédiatement attachée à une déclaration documentable. Elle n'est jamais un commentaire libre à l'intérieur d'un corps exécutable.
Déclarations documentables selon leur existence syntaxique : types nominaux, fonctions, méthodes, `clsmethod`, `operator`, `construct`, `destruct`, fields, variables/constants top-level ou membres, variants d'enum et autres éléments structurels explicitement retenus par leur grammaire.
Sont notamment interdits comme cible Saseldoc : variables/constantes locales, statements, expressions, blocs, branches `if`/`match`, paramètres pris isolément et contenu arbitraire d'une callable.
Une Saseldoc orpheline ou non attachée à une déclaration documentable est une erreur.
Les éléments non publics peuvent être documentés dans le source. Ils sont filtrés selon les paramètres de visibilité de `saseldoc` et doivent apparaître avec une indication structurelle/visuelle non ambiguë de leur visibilité dans les sorties qui les incluent.
Le `construct` suit sa visibilité Saselang réelle pour la documentation. `destruct`, qui ne porte pas de modificateur de visibilité utilisateur, est classé comme **private** pour la génération documentaire et n'apparaît donc pas dans une documentation publique.
Une génération publique ne doit pas afficher les membres privés comme un simple bloc annexe : ils sont absents si leur visibilité n'est pas incluse.
## 43.6 Marqueurs documentaires persistants — V1 REQUIS — FIGÉ EN PRINCIPE
Les marqueurs persistants appartiennent au format documentaire compris par `saseldoc`, pas à la grammaire ni à la sémantique du code Saselang.
Réservation initiale :
```text
@file-path
@package
@author
@created
@updated
@file-version
```
Leur rôle général est :
```text
@file-path chemin documentaire attendu, normalement relatif à la racine du package
@package identité/coordonnée du package concerné
@author auteur/contributeur associé
@created date de création documentaire
@updated date ou timestamp de dernière mise à jour documentaire
@file-version version propre au fichier, distincte de la version package
```
Les variables éventuelles de template ou de génération telles que `@current-timestamp`, `@current-date`, `@current-author`, `@current-file-path` ou valeurs tirées d'un manifest ne font pas partie de Saselang ni du contrat obligatoire de `saseldoc`. Elles peuvent être interprétées/remplacées par un IDE, un générateur de template ou un outil tiers.
Un marqueur `@...` inconnu dans un commentaire documentaire ne doit pas faire échouer `saseldoc` : il reste contenu documentaire opaque/littéral si aucun outil externe ne l'a remplacé.
`@file-path` est documentaire ; le compilateur reste autoritaire sur le chemin physique, le `source_root`, le namespace et le nom déclaré. `saseldoc` peut signaler une incohérence documentaire mais le marqueur ne redéfinit jamais l'identité du symbole.
## 43.7 `saseldoc` — V1 REQUIS — FIGÉ EN PRINCIPE
`saseldoc` est l'unique générateur officiel. Il peut produire plusieurs vues et formats au moyen de paramètres, notamment documentation publique ou interne, format de sortie et destination.
La visibilité n'est pas réduite artificiellement à un ordre total lorsque les domaines `protected`, `module` et `package` ne sont pas sémantiquement comparables. L'interface de filtrage doit pouvoir exprimer les ensembles de visibilité nécessaires sans falsifier le modèle d'accès du langage.
Les signatures, types de paramètres, generics, visibilité, `Result`, `throws`, héritage et interfaces sont dérivés du modèle sémantique plutôt que redéclarés manuellement dans la Saseldoc.
Les formats exacts V1 restent à finaliser avec la CLI, mais un format de sortie n'implique jamais un outil séparé.
## 43.8 Shebang `.saselrun` — V1 REQUIS — FIGÉ EN PRINCIPE
Une ligne `#!...` peut être reconnue uniquement comme première ligne physique de `main.saselrun`. Elle est ignorée par la grammaire Saselang et sert de métadonnée de lancement pour l'environnement extérieur.
`#!` n'introduit pas un système d'attributs de style Rust. La commande de shebang recommandée sera définie lorsque la CLI finale sera figée.
## 43.9 Sasemark — V1 RÉSERVÉ / FUTUR
Format documentaire rigide dérivé de Markdown envisagé pour les spécifications/outils, mais distinct de la grammaire du langage et pouvant être spécifié séparément.
---

52
chapters/044-browser-futur-v3.md Normal file
View File

@@ -0,0 +1,52 @@
# 44. Browser — FUTUR V3+
## 44.1 Statut
Le browser runtime n'est pas une exigence d'implémentation V1.
Les décisions V1 doivent seulement préserver son intégration future.
## 44.2 Direction actuelle
Le browser Saselang pourra rester interprété tout en passant par une phase préalable de compilation/préparation :
```text
sources
-> semantic compile
-> résolution manifest/features/saselmod/compile if
-> Browser IR / bytecode
-> bundle/chunks
-> browser runtime interpreter
```
Le browser n'a donc pas besoin d'accéder directement au manifest ou aux `module.saselmod` originaux.
## 44.3 Chunks
Direction envisagée :
```text
source unit
-> browser compilation unit
-> chunk transportable
```
En développement, une granularité proche d'un source par chunk peut être utilisée.
En production, plusieurs unités peuvent être regroupées et chargées à la demande.
Les chunks d'un même déploiement doivent partager un fingerprint compatible de build/runtime/dependencies/features.
## 44.4 `.saselscript`
Le `.saselscript` est l'entrée logique browser et pourra charger/initialiser le graphe de chunks.
La spécification finale est volontairement reportée après V2.
## 44.5 `browser-binary`
Type de package futur possible, distinct de `bin` et `lib`.
La direction actuelle est conservée comme idée, pas comme contrat V1 définitif.
---

19
chapters/045-autres-backends-cibles-futur-v3.md Normal file
View File

@@ -0,0 +1,19 @@
# 45. Autres backends/cibles — FUTUR V3+
Prévisions :
```text
WebAssembly
JVM bytecode
JavaScript
TypeScript
Android
iOS
BSD supplémentaires
embedded avancé
interpréteurs spécialisés
```
Ils doivent réutiliser le frontend/HIR/Sase IR plutôt que créer des dialectes Saselang divergents.
---

18
chapters/046-quantique-futur-lointain-reserve.md Normal file
View File

@@ -0,0 +1,18 @@
# 46. Quantique — FUTUR LOINTAIN / RÉSERVÉ
L'architecture ne doit pas interdire une future extension QPU.
Noms réservés/envisagés :
```text
qoperation
quantum
measure
adjoint
controlled
Qubit
```
Ne pas réserver prématurément des mots génériques tels que `use` ou `borrow` tant que le modèle mémoire n'est pas figé.
---

37
chapters/047-concepts-rejetes-ou-deconseilles.md Normal file
View File

@@ -0,0 +1,37 @@
# 47. Concepts rejetés ou déconseillés
## 47.1 Rejetés
```text
traits séparés des interfaces en V1
multiple class inheritance
implicit returns
global general type inference for variable identity
variable shadowing while previous declaration visible
operator aliases sans différence sémantique
user-defined arbitrary operator symbols
operator ++ / --
operator === / !==
operator >>>
C preprocessor #ifdef/#define
switch/case fallthrough
errdefer
general static keyword when clsmethod suffices
match guards `when` / `if`
loop/until/repeat/unless comme synonymes de structures existantes
magic getters/setters
mandatory native GC
```
## 47.2 À éviter sauf besoin démontré
```text
reflection runtime obligatoire
metaprogramming transformant silencieusement le code
features combinatoires non contraintes
package hybride `lib+bin`
exports/reexports dans module.saselmod
transitive dependencies importables sans déclaration directe
```
---

112
chapters/048-inventaire-des-points-v1-encore-ouverts.md Normal file
View File

@@ -0,0 +1,112 @@
# 48. Inventaire des points V1 encore OUVERTS
Cette section constitue la checklist principale avant de considérer la Bible V1 comme suffisamment normative pour une implémentation complète.
## 48.1 Lexical / grammaire
Points désormais largement figés : UTF-8 source, code ASCII hors contenu textuel, whitespace non sémantique, identifiants ASCII, commentaires, Saseldoc, littéraux numériques, `char`, String normales/raw/multilignes, escapes, séparateurs numériques, règles de fichiers source, statements/blocs/`;`, absence de trailing comma, `if`/`elseif`/`else`, boucles de base, `match`, `emit` et noyau des patterns structurels.
Restent à fermer :
- liste exhaustive finale des mots-clés actifs, futurs et `reserved-foreign` après audit de toute la Bible ;
- choix canonique `{expr}` vs `${expr}` à l'intérieur de `i"..."` ;
- matrice finale des préfixes de littéraux combinables (`i`, `r`, `b`, `c`, `u8/u16/u32`, `t`, etc.) et leur disponibilité V1/V2 ;
- limite normative éventuelle du nombre de `#` des raw strings ;
- grammaire syntaxique complète au-delà des blocs/statements déjà figés ;
- syntaxe exacte des generics et contraintes ;
- syntaxe exacte des annotations/métadonnées de code lorsqu'elles seront retenues.
## 48.2 Types
- domaine exact des types admissibles à `Nullable<T>` avec le modèle mémoire/FFI ;
- finalisation de la matrice exhaustive des conversions numériques Core et de ses noms composés ;
- règles de sous-typage interface/class ;
- generics complets ;
- const generics ;
- callable/function types ;
- lambdas/closures ;
- variadiques (un seul variadique prévu) ;
- String/index Unicode ;
- exact float semantics.
## 48.3 Mémoire
- value/reference model ;
- object allocation ;
- ownership/move/copy/clone ;
- references/borrowing visibles ou internes ;
- allocator ;
- cycles ;
- destruction partielle ;
- thread safety ;
- raw pointers ;
- unsafe operation inventory.
## 48.4 Erreurs
Points désormais largement figés : hiérarchie `Error` / `ResultError` / `Exception`, `Result::Ok` / `Result::Err`, contraintes de `Result<T,E>`, absence de `unwrap` et `?` V1, `throw` / `throws`, contrats d'override/interface, sélection ordonnée des `catch`, `finally` non-escaping, causes, i18n, code de `ResultError`, stack trace d'`Exception` liée au `throw`, et sémantique LIFO/non-escaping de `defer`.
Restent à fermer :
- faute runtime/panic/fatal error ;
- constructors faillibles et construction partielle ;
- interaction exacte cleanup/destruction pendant fault ;
- ordre exact `defer` / destructeurs automatiques avec le modèle mémoire ;
- représentation Core/runtime exacte de `I18nMessage`, `ResultErrorCode`, `StackTrace` et `StackFrame` ;
- éventuels helpers Core futurs `expectOk` / `expectErr` seulement si un besoin réel est démontré.
## 48.5 Contrôle de flux
- harmonisation finale des literal/named-constant patterns avec les règles générales des constantes et des types ;
- détails d'implémentation/Core des capacités Range et organisation de leurs namespaces ;
- generators/yield décision V1 ;
- lambdas ;
- async/concurrency.
## 48.6 Opérateurs
- signatures exactes des membres des interfaces `Op...` ;
- relation précise PartialEqual/Equal et PartialCompare/Compare ;
- règles de comparaison hétérogène et reverse implementation ;
- index assignability formelle ;
- bitcast safe/unsafe table ;
## 48.7 Object model
- `protected` via autres instances ;
- clsmethod inheritance exact ;
- associated constants interface ;
- conflict resolution syntax when choosing among defaults ;
- visibility/default visibility if omitted (préférence actuelle : explicite) ;
- precise constructor synthesis grammar.
## 48.8 Packages/tooling
- grammaire finale des imports `from "vendor/package@requirement"` ;
- format TOML sérialisé exact de `saselang.lock` ;
- détails FFI/linker des composants physiques des variants natifs, après fixation complète de la FFI ;
- syntaxe TOML finale des features et groupes de features ;
- syntaxe exacte des directives `module.saselmod` ;
- syntaxe exacte de `compile if` et de ses éventuels `else` ;
- API Core/compiler exacte de l'environnement de compilation ;
- choix final `enum` vs identifiant extensible pour quelques domaines Core lors de l'implémentation, sans changer le modèle conceptuel ;
- liste des targets LLVM officiellement validés par la première toolchain V1 ;
- ordre final des entrées `.saselib` après le manifest interne et niveau Zstandard canonique, après benchmark ;
- sémantique détaillée du mode `standalone` face aux bibliothèques non redistribuables/dynamiques ;
- grammaire CLI finale des options et sélecteurs de projet ;
- liste finale des options backend LLVM au-delà de `lto`, uniquement si elles sont nécessaires ;
- détails de `saseldoc` après fixation du format documentaire et des tests.
## 48.9 Core/SDK
- frontière Core/SDK définitive ;
- collections V1 ;
- String encodings ;
- regex ;
- filesystem/network/process ;
- math/algebra ;
- logging/tracing ;
- testing APIs ;
- reflection/TypeInfo.
---

20
chapters/049-elements-v1-reserves-mais-non-obligatoires-a-implementer-immediatement.md Normal file
View File

@@ -0,0 +1,20 @@
# 49. Éléments V1 RÉSERVÉS mais non obligatoires à implémenter immédiatement
```text
.saselscript
yield si generators différés
browser-binary
Sasemark
hexadecimal floating literals si différés de V1
b/br byte-string literals
u8/u16/u32 explicit-encoding literals
c/cr C-string literals
t structured-template literals
certaines combinaisons de préfixes texte utiles
certains backends/tooling hooks
noms nécessaires pour éviter collisions futures
```
Un élément réservé ne doit pas être réutilisé pour une fonctionnalité incompatible.
---

19
chapters/050-elements-futurs-v3-identifies.md Normal file
View File

@@ -0,0 +1,19 @@
# 50. Éléments FUTURS V3+ identifiés
```text
browser runtime/extension définitif
browser chunks/bundler optimisé
browser-binary définitif
WebAssembly backend complet
JVM backend
JavaScript/TypeScript backends
Android packaging
iOS packaging
packagers OS avancés
runtime capability discovery avancée
quantum/QPU
```
Ces sections sont informatives et peuvent évoluer. V1 et V2 étant des générations internes, elles peuvent encore recevoir des corrections incompatibles documentées. La protection stricte de la compatibilité publique devient un objectif à partir de la première génération distribuée publiquement, envisagée en V3+.
---

23
chapters/051-invariants-de-conception.md Normal file
View File

@@ -0,0 +1,23 @@
# 51. Invariants de conception
Les futures décisions doivent respecter les invariants suivants :
1. **Une sémantique Saselang ne change pas silencieusement selon le backend.**
2. **Le frontend reste indépendant de LLVM.**
3. **V1 est suffisamment complet pour construire le compilateur/interpréteur sans inventer des règles pendant l'implémentation.**
4. **V2 doit pouvoir réimplémenter V1 en Saselang.**
5. **Les décisions V1 évitent de bloquer les backends V3+ sans prétendre les spécifier définitivement.**
6. **Pas de préprocesseur textuel.**
7. **Pas de magie lorsque la même capacité peut être exprimée explicitement et de façon déterministe.**
8. **Pas de duplication de concepts par des alias syntaxiques gratuits.**
9. **Les types Core compiler-known restent peu nombreux.**
10. **Le package, le namespace, le target, la feature, la capability et l'artifact restent des dimensions distinctes.**
11. **Une collision de namespace entre packages ne doit jamais fusionner implicitement leurs types.**
12. **Les erreurs récupérables utilisent `Result`; les opérations réellement infaillibles retournent directement leur valeur.**
13. **`throws` n'existe que sur une callable retournant `Result`.**
14. **L'identité d'objet est distincte de l'égalité de valeur.**
15. **Les opérateurs utilisateur passent uniquement par les contrats Core `Op...`.**
16. **Les interfaces fournissent l'héritage multiple de contrats/comportements sans introduire un second système de traits.**
17. **Le modèle mémoire V1 doit fournir performances, sûreté et destruction déterministe sans imposer des lifetimes explicites partout.**
---

23
chapters/052-priorite-de-specification-apres-0-2-9.md Normal file
View File

@@ -0,0 +1,23 @@
# 52. Priorité de spécification après 0.2.12
Pour transformer cette Bible en spécification V1 directement implémentable, l'ordre recommandé est :
```text
1. terminer casts/conversions numériques + matrice Core
2. generics + contraintes + const generics
3. String/Unicode + collections + Range
4. lambdas/closures + callable model
5. async/concurrency décision V1
6. modèle mémoire + allocator + pointers + unsafe
7. fautes runtime + construction/destruction cleanup
8. Core V1 exact et capacités target
9. SDK V1 initial et frontières Core/SDK
10. FFI C exacte
11. reflection/metadata/tests/tooling
12. grammaire syntaxique complète et audit lexical final
13. audit complet de toutes les sections V1 REQUIS — À FINALISER
14. consolidation examples / DO-DON'T / conformance tests
15. plan d'implémentation du compilateur/interpréteur V1
```
La Bible ne doit être déclarée « V1 specification complete » qu'après fermeture de tous les points V1 REQUIS — À FINALISER qui affectent la grammaire ou la sémantique observable.

11
examples/000-statuts-normatifs-examples.md Normal file
View File

@@ -0,0 +1,11 @@
# Exemples / DO-DON'T — Chapitre 0 — Statuts normatifs
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
Aucun bloc d'exemple explicite n'est encore présent dans ce chapitre.
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

63
examples/001-trajectoire-dimplementation-examples.md Normal file
View File

@@ -0,0 +1,63 @@
# Exemples / DO-DON'T — Chapitre 1 — Trajectoire d'implémentation
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
frontend complet
lexer
parser
AST
analyse sémantique
HIR
Sase IR
interpréteur
a backend LLVM
Core V1
SDK initial
manifests et workspaces
gestion des dépendances
outils initiaux
```
### Exemple 2
```text
représentable par le backend
mais non officiellement supportée par la toolchain Saselang
```
### Exemple 3
```text
compiler frontend
semantic analysis
Sase IR
interpreter
tooling
package/build tooling
Core/SDK lorsque pertinent
```
### Exemple 4
```text
browser runtime / extension
browser chunks/bundling
WebAssembly
JVM
JavaScript
TypeScript
Android packaging
iOS packaging
backends/ABI supplémentaires
outillage avancé
cibles spécialisées
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

116
examples/002-principes-generaux-du-langage-examples.md Normal file
View File

@@ -0,0 +1,116 @@
# Exemples / DO-DON'T — Chapitre 2 — Principes généraux du langage
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
and comme alias de &&
or comme alias de ||
=== en plus de l'identité explicite
++ et --
ternaire ?: si les formes productrices de `match`/`if` avec `emit` couvrent le besoin
```
### Exemple 2
```text
&& / || short-circuit
& / | / ^ logique eager sur bool
```
### Exemple 3
```text
keywords
identifiers
numeric literals
operators
punctuation
syntactic whitespace
namespace syntax
```
### Exemple 4
```text
String literals
char literals
ordinary comments
Saseldoc comments
```
### Exemple 5
```text
U+0020 SPACE
U+0009 TAB
U+000A LF
U+000D CR
```
### Exemple 6
```regex
[A-Za-z_][A-Za-z0-9_]*
```
### Exemple 7
```text
_value // utilisateur autorisé
__value // réservé interne
```
### Exemple 8
```text
( ) grouping, calls, control headers, parameters
[ ] indexing et constructions définies par leur grammaire
{ } blocks et constructions à accolades
; fin d'un statement ou d'une déclaration sans corps
, séparation de deux éléments ; séparateur de listes init/update dans for
. qualification de namespace
:: qualification de membre/symbole
=> séparateur grammatical pattern -> bloc dans match
= assignment
+ - * / % arithmetic
& | ^ ~ bitwise/logical selon type ; | sépare aussi les alternatives d'un pattern
! logical negation / !=
< > comparaison, shifts et syntaxe générique selon contexte
.. famille de délimiteurs de Range, avec >.., ..< et >..<
' char delimiter
" String delimiter
_ identifiant / séparateur numérique / wildcard de pattern selon contexte
```
### Exemple 9
```text
# raw-string delimiter et shebang autorisé seulement selon sa règle dédiée
@ réservé hors commentaires/Saseldoc
$ réservé, notamment pendant la finalisation de l'interpolation
? réservé sans sémantique V1 encore attribuée
` réservé/interdit à l'utilisateur
\ uniquement selon les règles d'escape des littéraux
```
### Exemple 10
```text
Map<String,List<int32>>
```
### Exemple 11
```text
{
int32 myvar = 42;
}
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

41
examples/003-architecture-de-compilation-examples.md Normal file
View File

@@ -0,0 +1,41 @@
# Exemples / DO-DON'T — Chapitre 3 — Architecture de compilation
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Source
-> lexer
-> parser
-> AST
-> modèle sémantique
-> HIR
-> Sase IR
-> backend / interpréteur
```
### Exemple 2
```text
HIR
Sase IR
bytecode dérivé de Sase IR
```
### Exemple 3
```text
machine code
object file
native executable
static library
dynamic/shared library
textual assembly
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

77
examples/004-couches-de-lecosysteme-v1-examples.md Normal file
View File

@@ -0,0 +1,77 @@
# Exemples / DO-DON'T — Chapitre 4 — Couches de l'écosystème V1
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
grammaire
types primitifs
types nominaux
fonctions/méthodes
classes
structs
interfaces
enums
unions
tuples
generics
contrôle de flux
erreurs/exceptions
opérateurs
unsafe
scope
visibilité
imports
compilation conditionnelle structurelle
```
### Exemple 2
```text
Object
String
Result<T>
Result<T,E>
Error
ResultError
Exception
Option<T>
Nullable<T>
Range<T>
RangeIterable<T>
RangeStep<T,Step>
RangeReverse<T>
RangeReverseStep<T,Step>
RangeProgression<T,Step>
Ordering
Op...
Iterable<T>
Iterator<T>
Array<T>
StaticArray<T,N>
TypeInfo
ExitCode
```
### Exemple 3
```text
collections
encodages explicites
regex
filesystem
networking
process
concurrence
math
algèbre
FFI helpers
plateforme
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

149
examples/005-types-primitifs-examples.md Normal file
View File

@@ -0,0 +1,149 @@
# Exemples / DO-DON'T — Chapitre 5 — Types primitifs
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
int8 int16 int32 int64 int128 int256
uint8 uint16 uint32 uint64 uint128 uint256
float16 float32 float64 float128
bool
char
```
### Exemple 2
```text
-> Void
Result<Void,E>
Result<Void>
```
### Exemple 3
```text
func save() -> Result<Void> {
...
return Result::Ok(Void);
}
```
### Exemple 4
```text
Void value;
field Void
Option<Void>
Nullable<Void>
Array<Void>
Range<Void>
```
### Exemple 5
```text
value::toString()
float16::fromInt32(value)
```
### Exemple 6
```text
overflow statiquement prouvable -> erreur de compilation
overflow dynamique -> faute runtime déterministe
```
### Exemple 7
```text
wrapping
saturating
checked
```
### Exemple 8
```text
statique -> erreur compilation
dynamique -> faute runtime
```
### Exemple 9
```text
a == (a / b) * b + (a % b)
```
### Exemple 10
```text
42 decimal
0b101010 binary
0o52 octal
0x2a hexadecimal
```
### Exemple 11
```text
1_000_000
0b1010_1100
0xffff_ffff
1.234_567
1.0e1_000
```
### Exemple 12
```text
1.0
0.5
42.25
1e6
1.5e-3
```
### Exemple 13
```text
i8 i16 i32 i64 i128 i256
u8 u16 u32 u64 u128 u256
f16 f32 f64 f128
```
### Exemple 14
```text
42i32
42u64
1.5f16
```
### Exemple 15
```text
0x1.0p0
0x1.8p1
0x1.ffp10
0x1.0p-20
```
### Exemple 16
```text
1f16
1::toFloat16()
```
### Exemple 17
```text
bitcast<float16>(value)
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

26
examples/006-types-variables-constantes-et-scopes-examples.md Normal file
View File

@@ -0,0 +1,26 @@
# Exemples / DO-DON'T — Chapitre 6 — Types, variables, constantes et scopes
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
{
int32 value = 1;
}
{
int32 value = 2;
}
```
### Exemple 2
```text
foo(a(), b(), c())
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

19
examples/007-types-nominaux-et-fichiers-saseltype-examples.md Normal file
View File

@@ -0,0 +1,19 @@
# Exemples / DO-DON'T — Chapitre 7 — Types nominaux et fichiers `.saseltype`
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
class
struct
interface
enum
union
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

54
examples/008-classes-et-object-examples.md Normal file
View File

@@ -0,0 +1,54 @@
# Exemples / DO-DON'T — Chapitre 8 — Classes et `Object`
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
open
ou
final
```
### Exemple 2
```text
abstract
```
### Exemple 3
```text
this instance courante
super instance de la classe parente immédiate
cls classe courante dans une clsmethod
parent classe parente immédiate dans une clsmethod
```
### Exemple 4
```text
super::super
parent::parent
```
### Exemple 5
```text
this::field
token::kind()
Type::member
super::method()
```
### Exemple 6
```text
Object::sameInstance(Object other) -> bool
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

18
examples/009-structs-examples.md Normal file
View File

@@ -0,0 +1,18 @@
# Exemples / DO-DON'T — Chapitre 9 — Structs
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
private
module
package
public
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

11
examples/010-enums-algebriques-examples.md Normal file
View File

@@ -0,0 +1,11 @@
# Exemples / DO-DON'T — Chapitre 10 — Enums algébriques
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
Aucun bloc d'exemple explicite n'est encore présent dans ce chapitre.
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

28
examples/011-tuples-examples.md Normal file
View File

@@ -0,0 +1,28 @@
# Exemples / DO-DON'T — Chapitre 11 — Tuples
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
(int32, String)
```
### Exemple 2
```text
(int32 id, String name) = value;
```
### Exemple 3
```text
tuple[0]
tuple[1]
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

40
examples/012-unions-examples.md Normal file
View File

@@ -0,0 +1,40 @@
# Exemples / DO-DON'T — Chapitre 12 — Unions
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
int*
uint*
float*
```
### Exemple 2
```text
public unsafe union RawValue
```
### Exemple 3
```text
bool
char
raw pointers
fixed compatible arrays
FFI-safe trivial structs
compatible unsafe unions
```
### Exemple 4
```text
public unsafe extern "C" union NativeValue
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

45
examples/013-interfaces-examples.md Normal file
View File

@@ -0,0 +1,45 @@
# Exemples / DO-DON'T — Chapitre 13 — Interfaces
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
nom
+ ordre des paramètres
+ type de chaque paramètre
```
### Exemple 2
```text
type de retour
visibilité
fallibilité / Result
throws
contraintes génériques pertinentes
modificateurs contractuels pertinents
```
### Exemple 3
```text
module
package
public
```
### Exemple 4
```text
public interface Ring<T> {
public const T Zero;
public const T One;
}
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

32
examples/014-generics-examples.md Normal file
View File

@@ -0,0 +1,32 @@
# Exemples / DO-DON'T — Chapitre 14 — Generics
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Array<T>
Result<T,E>
OpAdd<Lhs,Rhs,Out>
```
### Exemple 2
```text
syntaxe des contraintes
variance ou absence de variance
contraintes multiples
specialization éventuelle
monomorphisation vs représentation partagée
contraintes sur types primitifs
const generics pour StaticArray<T,N>
generic methods
inférence éventuelle des arguments génériques à l'appel
wildcards/existentials éventuels
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

53
examples/015-fonctions-methodes-et-clsmethod-examples.md Normal file
View File

@@ -0,0 +1,53 @@
# Exemples / DO-DON'T — Chapitre 15 — Fonctions, méthodes et `clsmethod`
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
func fonction libre
method méthode d'instance
clsmethod méthode de classe
operator implémentation d'un contrat opérateur
```
### Exemple 2
```text
opération infaillible
-> retourne directement T
opération pouvant produire une erreur récupérable
-> retourne Result<T>
ou Result<T,E>
```
### Exemple 3
```text
method length() -> uint64
method containsKey(K key) -> bool
Object::sameInstance(Object other) -> bool
func min(int32 a, int32 b) -> int32
```
### Exemple 4
```text
func readFile(String path) -> Result<String, IoError>
method parse(String input) -> Result<Value, ParseError>
```
### Exemple 5
```text
return value;
return Result::Ok(value);
return Result::Ok(Void);
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

64
examples/016-dispatch-override-et-modificateurs-examples.md Normal file
View File

@@ -0,0 +1,64 @@
# Exemples / DO-DON'T — Chapitre 16 — Dispatch, override et modificateurs
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
visibility
-> safety
-> linkage / ABI
-> type / dispatch modifiers
-> override
-> declaration kind
```
### Exemple 2
```text
Name<...>
-> extends ...
-> implements ...
```
### Exemple 3
```text
public final class User
public open class Service
public abstract class Base
public unsafe extern "C" union NativeValue
protected open method calculate(...)
protected override method calculate(...)
protected final override method calculate(...)
```
### Exemple 4
```text
open method
```
### Exemple 5
```text
abstract method
```
### Exemple 6
```text
override method
```
### Exemple 7
```text
final override method
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

51
examples/017-construction-et-destruction-examples.md Normal file
View File

@@ -0,0 +1,51 @@
# Exemples / DO-DON'T — Chapitre 17 — Construction et destruction
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
private
protected
module
package
public
```
### Exemple 2
```text
private
module
package
public
```
### Exemple 3
```text
C -> B -> A
```
### Exemple 4
```text
this::field
this::method()
super::method()
escape/capture/pass de this
```
### Exemple 5
```text
destruct() {
...
}
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

259
examples/018-result-erreurs-et-exceptions-examples.md Normal file
View File

@@ -0,0 +1,259 @@
# Exemples / DO-DON'T — Chapitre 18 — `Result`, erreurs et exceptions
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Object
└── Error
├── ResultError
└── Exception
```
### Exemple 2
```text
public final class ParseError extends ResultError {
}
public final class FileNotFoundException extends Exception {
}
```
### Exemple 3
```text
message: String
cause: Option<Error>
i18nMessage: Option<I18nMessage>
```
### Exemple 4
```text
message
message humain canonique / fallback
cause
erreur causale purement informative
peut contenir un ResultError ou une Exception
n'est pas automatiquement propagée
i18nMessage
clé et paramètres de localisation
ne contient pas un tableau de traductions
```
### Exemple 5
```text
code: ResultErrorCode
```
### Exemple 6
```text
code -> stable, machine-readable, non localisé
message -> humain, canonique / fallback
i18nMessage -> localisation externe
```
### Exemple 7
```text
throw exception;
```
### Exemple 8
```text
Result::Ok(T)
Result::Err(E)
```
### Exemple 9
```text
E doit être ResultError ou un descendant de ResultError
```
### Exemple 10
```text
Result<Data,ResultError>
Result<Data,ParseError>
Result<Void,ResultError>
```
### Exemple 11
```text
Result<Data,Error>
Result<Data,Exception>
Result<Data,FileNotFoundException>
```
### Exemple 12
```text
Result<T>
```
### Exemple 13
```text
Result<T,ResultError>
```
### Exemple 14
```text
return Result::Ok(value);
return Result::Err(error);
```
### Exemple 15
```text
result::expectOk(...)
result::expectErr(...)
```
### Exemple 16
```text
ResultError -> Exception
Exception -> ResultError
```
### Exemple 17
```text
throw ParseException(..., Option::Some(parseError));
```
### Exemple 18
```text
catch (FileNotFoundException error) {
return Result::Err(FileResultError(..., Option::Some(error)));
}
```
### Exemple 19
```text
T + throws -> interdit
Result<T,E> -> valide sans throws
Result<T,E> + throws -> valide
```
### Exemple 20
```text
throws IOException
```
### Exemple 21
```text
supprimer entièrement des exceptions déclarées
restreindre une famille à une ou plusieurs sous-familles compatibles
gérer localement tout ou partie des exceptions du contrat parent
```
### Exemple 22
```text
throw FileNotFoundException(...); // valide
throw ParseError(...); // erreur
throw Error(...); // erreur
```
### Exemple 23
```text
catch (IOException error) {
throw error;
}
```
### Exemple 24
```text
try { ... }
try { ... } finally { ... }
finally { ... }
```
### Exemple 25
```text
try {
...
} catch (SpecificException error) {
...
} catch (ParentException error) {
...
} finally {
...
}
```
### Exemple 26
```text
catch (FileNotFoundException error) {
...
} catch (IOException error) {
...
}
```
### Exemple 27
```text
catch (IOException error) {
...
} catch (FileNotFoundException error) {
...
}
```
### Exemple 28
```text
fin normale du try
fin normale d'un catch
return traversant la construction
throw propagé
break / continue traversant la construction
Exception non capturée par les catch
```
### Exemple 29
```text
return
throw
break
continue
emit
```
### Exemple 30
```text
index hors limites
division entière par zéro
overflow checked
représentation mémoire invalide
borne dynamique invalide lors d'une construction directe lorsque la règle du type le définit
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

287
examples/019-controle-de-flux-examples.md Normal file
View File

@@ -0,0 +1,287 @@
# Exemples / DO-DON'T — Chapitre 19 — Contrôle de flux
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
if (condition) {
action();
} elseif (otherCondition) {
otherAction();
} else {
fallback();
}
```
### Exemple 2
```text
int32 result = if (x > 10) {
emit 1;
} elseif (x > 5) {
emit 2;
} else {
emit 3;
};
```
### Exemple 3
```text
Option<uint32> result = if (condition) {
emit Option::Some(42);
} else {
emit Option::None;
};
```
### Exemple 4
```text
match (value) {
pattern1 => {
statements;
}
pattern2 => {
statements;
}
_ => {
statements;
}
}
```
### Exemple 5
```text
literal pattern
enum variant pattern
tuple pattern
struct pattern
typed binding pattern
wildcard _
alternative pattern avec |
nested pattern
Range pattern si et seulement si le Range est valide selon les règles de Range
```
### Exemple 6
```text
1 | 2 | 3 => {
...
}
```
### Exemple 7
```text
A(uint32 value) | B(uint32 value) => {
use(value);
}
```
### Exemple 8
```text
Color::Red => {
...
}
```
### Exemple 9
```text
Result::Ok(uint32 value) => {
use(value);
}
Result::Err(Error error) => {
handle(error);
}
```
### Exemple 10
```text
Result::Ok(_) => {
...
}
```
### Exemple 11
```text
(0, 0) => {
origin();
}
(int32 x, 0) => {
horizontal(x);
}
(int32 x, int32 y) => {
other(x, y);
}
```
### Exemple 12
```text
Point {
x: 0,
y: int32 vertical
} => {
use(vertical);
}
```
### Exemple 13
```text
Point {
x: 0,
y: _
}
```
### Exemple 14
```text
SomeEnum::PointValue(
Point {
x: 0,
y: int32 y
}
) => {
use(y);
}
```
### Exemple 15
```text
int32 result = match (value) {
0 => {
emit 10;
}
_ => {
emit 20;
}
};
```
### Exemple 16
```text
int32 result;
result = if (condition) {
emit 1;
} else {
emit 2;
};
```
### Exemple 17
```text
return V1 requis
break V1 requis
continue V1 requis
yield réservé pour generators/coroutines si non finalisé en V1
```
### Exemple 18
```text
while (condition) {
...
}
dowhile (condition) {
...
}
for (initialization; condition; update) {
...
}
foreach (Type item in iterable) {
...
}
```
### Exemple 19
```text
dowhile (condition) {
statements;
}
```
### Exemple 20
```text
for (;;) {
...
}
```
### Exemple 21
```text
while (true) {
...
}
```
### Exemple 22
```text
for (i = 0, j = 5; i < x || j < y; i += 1, j += 1) {
...
}
```
### Exemple 23
```text
foreach (Type item in iterable) {
...
}
```
### Exemple 24
```text
until (...) -> utiliser while (!...)
repeat ... until -> utiliser dowhile (!...)
unless (...) -> utiliser if (!...)
loop { ... } -> utiliser while (true) { ... }
```
### Exemple 25
```text
;
;;
foo();;
```
### Exemple 26
```text
foo(first, second, third); // valide
foo(first, second, third,); // invalide
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

234
examples/020-operateurs-examples.md Normal file
View File

@@ -0,0 +1,234 @@
# Exemples / DO-DON'T — Chapitre 20 — Opérateurs
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
OpPositive<T>
OpNegate<T>
OpAdd<Lhs,Rhs,Out>
OpSubtract<Lhs,Rhs,Out>
OpMultiply<Lhs,Rhs,Out>
OpDivide<Lhs,Rhs,Out>
OpRemainder<Lhs,Rhs,Out>
```
### Exemple 2
```text
Vector3 * float64 -> Vector3
Matrix * Vector3 -> Vector3
Timestamp + Duration -> Timestamp
Timestamp - Timestamp -> Duration
```
### Exemple 3
```text
OpBitNot<T>
OpBitAnd<Lhs,Rhs,Out>
OpBitOr<Lhs,Rhs,Out>
OpBitXor<Lhs,Rhs,Out>
OpShiftLeft<T,Out>
OpShiftRight<T,Out>
```
### Exemple 4
```text
statique -> erreur compilation
dynamique -> faute runtime
```
### Exemple 5
```text
unsigned -> logical zero-fill
signed -> arithmetic sign extension
```
### Exemple 6
```text
!a
a && b
a || b
```
### Exemple 7
```text
a & b
a | b
a ^ b
```
### Exemple 8
```text
OpPartialEqual<Lhs,Rhs>
OpEqual<T>
```
### Exemple 9
```text
OpPartialEqual<T,T>
```
### Exemple 10
```text
réflexive
symétrique
transitive
```
### Exemple 11
```text
public enum Ordering {
Less,
Equal,
Greater,
Unordered
}
```
### Exemple 12
```text
OpPartialCompare<Lhs,Rhs>
OpCompare<T>
```
### Exemple 13
```text
OpIndex<Index,Read>
OpIndexMut<Index,Write>
```
### Exemple 14
```text
container[index]
container[index] = value
```
### Exemple 15
```text
Map<K,V>
OpIndex<K,Option<V>>
OpIndexMut<K,V>
```
### Exemple 16
```text
if (a = b) { ... }
x = (a = b);
a = b = c;
```
### Exemple 17
```text
+= -= *= /= %=
&= |= ^=
<<= >>=
```
### Exemple 18
```text
lecture
+ opérateur fondamental surchargeable
+ réaffectation
```
### Exemple 19
```text
value is Type
```
### Exemple 20
```text
value is Animal // true
value is Dog // true
value is Labrador // true
```
### Exemple 21
```text
!(value is Type)
```
### Exemple 22
```text
value instanceof ConcreteClass
```
### Exemple 23
```text
value instanceof Animal // false
value instanceof Dog // false
value instanceof Labrador // true
```
### Exemple 24
```text
!(value instanceof ConcreteClass)
```
### Exemple 25
```text
bitcast<T>(value)
```
### Exemple 26
```text
1. qualification / membre . ::
2. appel / indexation () []
3. préfixes +x -x !x ~x
4. multiplicatifs * / %
5. additifs + -
6. shifts << >>
7. relation / type < <= > >= is instanceof
8. égalité == !=
9. bitwise AND &
10. bitwise XOR ^
11. bitwise OR |
12. logique short-circuit AND &&
13. logique short-circuit OR ||
```
### Exemple 27
```text
a < b < c -> interdit
a == b == c -> interdit
```
### Exemple 28
```text
a < b && b < c
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

110
examples/021-strings-unicode-et-encodages-examples.md Normal file
View File

@@ -0,0 +1,110 @@
# Exemples / DO-DON'T — Chapitre 21 — Strings, Unicode et encodages
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Utf8String
Utf16String
Utf32String
AsciiString éventuel
Bytes
```
### Exemple 2
```text
byte
code unit
Unicode scalar
code point
grapheme cluster
```
### Exemple 3
```text
'A'
'é'
'中'
'😀'
'\n'
'\u{1F600}'
```
### Exemple 4
```text
"..." String normale, escapes actifs
"""...""" String normale multiligne
r"..." String brute
r"""...""" String brute multiligne
i"..." String interpolée
i"""...""" String interpolée multiligne
ir"..." interpolation + contenu brut, réservé
b"..." bytes, réservé
br"..." bytes bruts, réservé
u8"..." texte encodé UTF-8 explicitement, réservé
u16"..." texte encodé UTF-16 explicitement, réservé
u32"..." texte encodé UTF-32 explicitement, réservé
c"..." chaîne compatible C, réservé
cr"..." chaîne C brute, réservé
t"..." template structuré, réservé
```
### Exemple 5
```text
i"Hello {name}"
i"Hello ${name}"
```
### Exemple 6
```text
"""
first
second
"""
```
### Exemple 7
```text
r"simple"
r#"He said "hello"."#
r##"contains "# inside"##
```
### Exemple 8
```text
r"""..."""
r#"""..."""#
```
### Exemple 9
```text
\\ backslash
\" double quote
\' single quote
\n newline
\r carriage return
\t horizontal tab
\0 NUL
\u{...} Unicode scalar
```
### Exemple 10
```text
b"\x00\x7f\x80\xff"
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

124
examples/022-collections-et-iteration-examples.md Normal file
View File

@@ -0,0 +1,124 @@
# Exemples / DO-DON'T — Chapitre 22 — Collections et itération
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Vector<T>
```
### Exemple 2
```text
a..b [a, b] bornes basse et haute incluses
a>..b (a, b] borne basse exclue, borne haute incluse
a..<b [a, b) borne basse incluse, borne haute exclue
a>..<b (a, b) bornes basse et haute exclues
```
### Exemple 3
```text
Range<uint64> ids = 1..100;
```
### Exemple 4
```text
NaN interdit comme borne
+Infinity interdit comme borne
-Infinity interdit comme borne
valeur finie autorisée
```
### Exemple 5
```text
a..a contient exactement a
a>..a vide
a..<a vide
a>..<a vide
```
### Exemple 6
```text
range::lower()
range::upper()
range::includesLower()
range::includesUpper()
range::isEmpty()
range::contains(value)
```
### Exemple 7
```text
Range<T> intervalle ordonné
RangeIterable<T> parcours canonique vers l'avant
RangeStep<T,Step> parcours avant avec pas explicite
RangeReverse<T> parcours canonique vers l'arrière
RangeReverseStep<T,Step> parcours arrière avec pas explicite
RangeProgression<T,Step> valeur de progression produite
```
### Exemple 8
```text
(range)::step(step)
```
### Exemple 9
```text
RangeStep<int32,int32>
RangeStep<int32,uint32>
RangeStep<char,uint32>
RangeStep<Date,Duration>
```
### Exemple 10
```text
(range)::reverse()
(range)::reverse()::step(step)
```
### Exemple 11
```text
range
[::reverse()]
[::step(step)]
```
### Exemple 12
```text
(250u8..255u8)::step(2u8)
```
### Exemple 13
```text
250 252 254
```
### Exemple 14
```text
(1..10)::step(4)
```
### Exemple 15
```text
1 5 9
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

73
examples/023-optiont-et-nullablet-examples.md Normal file
View File

@@ -0,0 +1,73 @@
# Exemples / DO-DON'T — Chapitre 23 — `Option<T>` et `Nullable<T>`
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
Option<int32>
Option<String>
Option<MyStruct>
Option<MyClass>
```
### Exemple 2
```text
Option<MyClass>::None
```
### Exemple 3
```text
Nullable<MyClass>::Null
```
### Exemple 4
```text
T?
```
### Exemple 5
```text
Option<Nullable<MyClass>> autorisé
Nullable<Option<MyClass>> interdit
Nullable<Nullable<MyClass>> interdit
```
### Exemple 6
```text
Option::None
Option::Some(Nullable<MyClass>::Null)
Option::Some(instance non nulle)
```
### Exemple 7
```text
Option<T> absence sémantique
Nullable<T> nullabilité représentationnelle
```
### Exemple 8
```text
match (value) {
Option::Some(uint32 number) => {
...
}
Option::None => {
...
}
}
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

84
examples/024-casts-et-conversions-examples.md Normal file
View File

@@ -0,0 +1,84 @@
# Exemples / DO-DON'T — Chapitre 24 — Casts et conversions
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
conversion de valeur
cast de hiérarchie nominale
bitcast de représentation binaire
```
### Exemple 2
```text
int8 small = ...;
int32 large = small; // ERROR
int32 explicitLarge = small::toInt32(); // OK
```
### Exemple 3
```text
Dog dog = ...;
Animal animal = dog;
Serializable serializable = dog;
```
### Exemple 4
```text
Animal animal = ...;
if (animal is Dog) {
// animal est raffiné en Dog ici.
}
```
### Exemple 5
```text
toTarget()
conversion exacte et totale
tryToTarget()
conversion exacte pour la valeur courante, récupérable si impossible
roundToTarget()
perte de précision explicitement acceptée, conversion totale
tryRoundToTarget()
perte de précision explicitement acceptée, mais conversion pouvant échouer
saturateToTarget()
saturation explicite lorsqu'aucun arrondi supplémentaire n'est nécessaire
saturatingRoundToTarget()
arrondi + saturation explicitement annoncés
wrapToTarget()
wrapping entier explicite
```
### Exemple 6
```text
tryExactToInt32()
tryFloorToInt32()
tryCeilToInt32()
tryRoundToInt32()
tryTruncateToInt32()
```
### Exemple 7
```text
annexes/A-numeric-conversions.md
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

11
examples/025-lambdas-closures-callables-et-generators-examples.md Normal file
View File

@@ -0,0 +1,11 @@
# Exemples / DO-DON'T — Chapitre 25 — Lambdas, closures, callables et generators
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
Aucun bloc d'exemple explicite n'est encore présent dans ce chapitre.
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

23
examples/026-async-et-concurrence-examples.md Normal file
View File

@@ -0,0 +1,23 @@
# Exemples / DO-DON'T — Chapitre 26 — Async et concurrence
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
async/await ou autre modèle
Future/Promise Core ou SDK
threads natifs
structured concurrency éventuelle
cancellation
synchronisation
interaction avec Result/throws
interaction avec destruction déterministe
runtime minimal
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

44
examples/027-memoire-references-et-unsafe-examples.md Normal file
View File

@@ -0,0 +1,44 @@
# Exemples / DO-DON'T — Chapitre 27 — Mémoire, références et `unsafe`
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
value vs reference semantics
object allocation
moves/copies/clones
borrow/reference semantics si nécessaire
escape analysis
lifetimes internes
partial construction
partial destruction
cycles éventuels
resource ownership
thread-safety implications
```
### Exemple 2
```text
unsafe { ... }
unsafe func
unsafe method
unsafe clsmethod
unsafe construct
unsafe union
```
### Exemple 3
```text
unsafe variable
unsafe constant
unsafe field
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

67
examples/028-defer-et-nettoyage-examples.md Normal file
View File

@@ -0,0 +1,67 @@
# Exemples / DO-DON'T — Chapitre 28 — `defer` et nettoyage
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
{
acquireA();
defer {
releaseA();
}
acquireB();
defer {
releaseB();
}
work();
}
```
### Exemple 2
```text
releaseB();
releaseA();
```
### Exemple 3
```text
fin normale
return
throw
break
continue
emit quittant le scope concerné
```
### Exemple 4
```text
throw
-> unwind des scopes quittés
-> defer de ces scopes, LIFO
-> catch correspondant éventuel
-> defer du scope catch, LIFO
-> finally éventuel
-> continuation normale ou propagation
```
### Exemple 5
```text
return
throw
break
continue
emit
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

40
examples/029-ffi-et-abi-examples.md Normal file
View File

@@ -0,0 +1,40 @@
# Exemples / DO-DON'T — Chapitre 29 — FFI et ABI
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
extern "C"
```
### Exemple 2
```text
extern "C" func
unsafe extern "C" func
extern "C" union
unsafe extern "C" union
```
### Exemple 3
```text
C struct layout
C enum mapping
raw pointers
strings C
callbacks
function pointers
calling conventions
variadic C
alignment/packing
ownership across FFI
error propagation across ABI
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

25
examples/030-reflexion-metadonnees-et-tests-examples.md Normal file
View File

@@ -0,0 +1,25 @@
# Exemples / DO-DON'T — Chapitre 30 — Réflexion, métadonnées et tests
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
informations compiler-known
métadonnées conservées dans le binaire
réflexion runtime optionnelle
```
### Exemple 2
```text
compiler
test
documentation/tooling
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

39
examples/031-fichiers-source-v1-examples.md Normal file
View File

@@ -0,0 +1,39 @@
# Exemples / DO-DON'T — Chapitre 31 — Fichiers source V1
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
src/compiler/lexer/Token.saseltype
namespace compiler.lexer;
public final class Token { ... }
```
### Exemple 2
```text
<source_root>/main.saselrun
```
### Exemple 3
```text
module.saselmod
```
### Exemple 4
```text
doc module-wide
deprecated module-wide
policies module-wide (ex: forbid unsafe)
requirements de feature
target/capability requirements lorsque pertinent
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

33
examples/032-source-root-modules-et-namespaces-examples.md Normal file
View File

@@ -0,0 +1,33 @@
# Exemples / DO-DON'T — Chapitre 32 — Source root, modules et namespaces
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
src
```
### Exemple 2
```text
src/saselang/compiler/lexer/Token.saseltype
```
### Exemple 3
```text
namespace saselang.compiler.lexer;
```
### Exemple 4
```regex
[a-z][a-z0-9_]*
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

47
examples/033-imports-et-resolution-des-noms-examples.md Normal file
View File

@@ -0,0 +1,47 @@
# Exemples / DO-DON'T — Chapitre 33 — Imports et résolution des noms
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
import type saselang.compiler.lexer.Token;
import func saselang.compiler.lexer.tokenize;
import const saselang.compiler.config.MaxDepth;
import var saselang.runtime.state.CurrentMode;
```
### Exemple 2
```text
class
struct
enum
interface
union
```
### Exemple 3
```text
import type foo.Token;
```
### Exemple 4
```text
import type foo.Token as FooToken;
```
### Exemple 5
```text
saselang.compiler.lexer.Token
saselang.compiler.lexer::tokenize(...)
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

112
examples/034-packages-identite-et-collisions-de-namespaces-examples.md Normal file
View File

@@ -0,0 +1,112 @@
# Exemples / DO-DON'T — Chapitre 34 — Packages, identité et collisions de namespaces
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
vendor/package
```
### Exemple 2
```text
vendor/package@version
```
### Exemple 3
```text
vendor/package@requirement
```
### Exemple 4
```text
saselang/core@1.4.0
saselang/compiler-core@^0.8
acme/http-client@>=2.5,<3.0
sdl/sdl@3.1.*
```
### Exemple 5
```regex
[a-z][a-z0-9]*(?:-[a-z0-9]+)*
```
### Exemple 6
```text
namespace parser.ast;
public class Node
```
### Exemple 7
```text
instance de package résolue
+ namespace
+ symbole
```
### Exemple 8
```text
acme/parser@2.4.1 :: parser.ast.Node
other/parser@5.0.0 :: parser.ast.Node
```
### Exemple 9
```text
from "vendor/package@requirement"
```
### Exemple 10
```text
import func some.namespace::function from "sdl/sdl@2.1.*" as sdlfun1;
import type some.namespace.Type from "acme/parser@^3.0" as ParserType;
```
### Exemple 11
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
### Exemple 12
```text
import func ... from "sdl/sdl@2.1.*" as sdlfun1;
import func ... from "sdl/sdl@^3.0" as sdlfun2;
```
### Exemple 13
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
### Exemple 14
```text
sdl/sdl@>=1.0
sdl/sdl@^4.5
```
### Exemple 15
```text
sdl/sdl@^3.0
sdl/sdl@3.1.*
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

233
examples/035-manifests-et-workspaces-examples.md Normal file
View File

@@ -0,0 +1,233 @@
# Exemples / DO-DON'T — Chapitre 35 — Manifests et workspaces
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
workspace.manifest.toml
project.manifest.toml
```
### Exemple 2
```toml
manifest-version = 1
```
### Exemple 3
```toml
manifest-version = 1
[workspace]
projects-root = "projects"
members = [
"core",
"compiler",
"sdk",
]
[workspace.output]
build-root = "build"
temp-build-root = ".saselang/tmp"
[workspace.defaults.project]
vendor = "saselang"
version = "0.1.0"
license = "..."
authors = ["..."]
repository = "..."
[workspace.defaults.source]
root = "src"
[workspace.defaults.build]
profile = "dev"
target = "host"
[workspace.defaults.paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]
[workspace.dependencies."saselang/core@^1.0"]
source = "registry"
[workspace.dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"
[workspace.dependencies."local/tools@^1.0"]
source = "local"
path = "../shared/tools"
```
### Exemple 4
```text
build-root
racine des sorties de build persistantes
temp-build-root
racine des fichiers temporaires/intermédiaires de build
```
### Exemple 5
```text
workspace.defaults.project
workspace.defaults.source
workspace.defaults.build
workspace.defaults.paths
```
### Exemple 6
```text
scalaire absent dans le projet
-> valeur workspace héritée
scalaire présent dans le projet
-> remplacement
liste absente dans le projet
-> liste workspace héritée
liste présente dans le projet
-> remplacement complet de la liste
```
### Exemple 7
```text
vendor/package@requirement
```
### Exemple 8
```text
workspace
local
git
registry
native
system
```
### Exemple 9
```toml
manifest-version = 1
[project]
vendor = "acme"
name = "my-application"
version = "1.2.0"
type = "bin"
description = "..."
license = "..."
authors = ["..."]
repository = "..."
[source]
root = "src"
[build]
profile = "dev"
target = "host"
[paths]
dependencies = ["vendor"]
native-libraries = ["native/lib"]
native-includes = ["native/include"]
[dependencies]
"saselang/core@^1.0" = { workspace = true }
[build.dependencies]
[dev.dependencies]
[dev.unit.dependencies]
[dev.integration.dependencies]
[dev.environment.dependencies]
```
### Exemple 10
```text
vendor
name
version
type
```
### Exemple 11
```text
description
license
authors
repository
```
### Exemple 12
```text
src
```
### Exemple 13
```text
profile
target
```
### Exemple 14
```text
dependencies
native-libraries
native-includes
```
### Exemple 15
```toml
[dependencies]
"saselang/core@^1.0" = { workspace = true }
```
### Exemple 16
```toml
[dependencies."acme/math@^2.4"]
source = "git"
url = "https://example.invalid/acme/math.git"
```
### Exemple 17
```text
valeurs intrinsèques/defaults du langage/toolchain
< workspace.defaults.*
< project.manifest.toml
< options explicites de la commande de build lorsque l'option est conçue pour être overridable
```
### Exemple 18
```text
lib
bin
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

95
examples/036-semver-et-politique-de-releases-examples.md Normal file
View File

@@ -0,0 +1,95 @@
# Exemples / DO-DON'T — Chapitre 36 — SemVer et politique de releases
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
MAJOR.MINOR.PATCH
```
### Exemple 2
```text
MAJOR -> rupture de compatibilité publique
MINOR -> ajout rétrocompatible
PATCH -> correction rétrocompatible
```
### Exemple 3
```text
pre -> alpha -> beta -> rc -> stable
```
### Exemple 4
```text
pre développement/intégration active ; fonctionnalités incomplètes possibles
alpha ensemble cohérent et testable ; API encore susceptible d'évoluer
beta fonctionnalités prévues essentiellement complètes ; stabilisation
rc candidat à la release ; changements limités aux corrections nécessaires
stable aucun identifiant de prerelease
```
### Exemple 5
```text
X.Y.Z-0.pre.N
X.Y.Z-1.alpha.N
X.Y.Z-2.beta.N
X.Y.Z-3.rc.N
X.Y.Z
```
### Exemple 6
```text
1.4.0-0.pre.3
1.4.0-1.alpha.1
1.4.0-2.beta.2
1.4.0-3.rc.1
1.4.0
```
### Exemple 7
```text
X.Y.Z-0.pre.N.fix.M
X.Y.Z-1.alpha.N.fix.M
X.Y.Z-2.beta.N.fix.M
X.Y.Z-3.rc.N.fix.M
```
### Exemple 8
```text
1.4.0-3.rc.2
1.4.0-3.rc.2.fix.1
1.4.0-3.rc.3
```
### Exemple 9
```text
1.4.0
```
### Exemple 10
```text
1.4.1
```
### Exemple 11
```text
X.Y.Z+build.N
X.Y.Z+doc.N
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

260
examples/037-dependances-et-scopes-examples.md Normal file
View File

@@ -0,0 +1,260 @@
# Exemples / DO-DON'T — Chapitre 37 — Dépendances et scopes
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
kind = nature logique de la dépendance
source = moyen utilisé pour la localiser/résoudre
```
### Exemple 2
```text
saselang
native
```
### Exemple 3
```text
workspace
registry
local
git
artifact
system
```
### Exemple 4
```toml
[dependencies."vendor/package@requirement"]
kind = "saselang"
source = "registry"
locator = "saselang"
```
### Exemple 5
```toml
foo = "^1.2"
foo = "../foo"
```
### Exemple 6
```text
vendor/package@requirement
```
### Exemple 7
```toml
[dependencies."acme/math@^2.4"]
kind = "saselang"
source = "git"
locator = "https://example.org/acme/math.git"
```
### Exemple 8
```toml
[dependencies."acme/local-tools@^1.0"]
kind = "saselang"
source = "local"
locator = "../local-tools"
```
### Exemple 9
```toml
[dependencies."acme/parser@=1.4.2"]
kind = "saselang"
source = "artifact"
locator = "../libs/parser.saselib"
```
### Exemple 10
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```
### Exemple 11
```toml
[workspace.dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
```
### Exemple 12
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "workspace"
```
### Exemple 13
```text
dependencies
build.dependencies
dev.dependencies
dev.unit.dependencies
dev.integration.dependencies
dev.environment.dependencies
```
### Exemple 14
```text
dev.benchmark.dependencies
dev.documentation.dependencies
dev.example.dependencies
```
### Exemple 15
```text
dev.unit effective =
dependencies
+ dev.dependencies
+ dev.unit.dependencies
```
### Exemple 16
```text
vendor/package
```
### Exemple 17
```text
sdl/sdl@2.1.*
sdl/sdl@^3.0
```
### Exemple 18
```text
sdl/sdl@^3.0
sdl/sdl@3.1.*
```
### Exemple 19
```text
vendor/package@requirement
```
### Exemple 20
```text
vendor/package@requirement
```
### Exemple 21
```text
sdl/sdl@^3.0
```
### Exemple 22
```text
Linux -> libSDL3.so / SONAME approprié
Windows -> SDL3.dll + import library éventuelle
macOS -> libSDL3.dylib ou framework approprié
```
### Exemple 23
```toml
[dependencies."sdl/sdl@^3.0"]
kind = "native"
source = "system"
locator = "SDL3"
[[dependencies."sdl/sdl@^3.0".variants]]
platform = "linux"
library = "SDL3"
[[dependencies."sdl/sdl@^3.0".variants]]
platform = "windows"
library = "SDL3"
```
### Exemple 24
```text
target-family
platform
architecture
abi
distribution
distribution-version
capabilities
```
### Exemple 25
```text
variant A : platform=linux, architecture=x86_64
variant B : platform=linux, abi=gnu
```
### Exemple 26
```text
library
linkage = auto | static | shared
deployment = auto | external | bundled
search-paths
include-paths
```
### Exemple 27
```text
runtime-files
link-files/import-libraries
frameworks
system-packages
resources
plugins
```
### Exemple 28
```text
=1.4.7
^4.5
~1.4.2
3.1.*
>=1.0
>=1.2,<2.0
```
### Exemple 29
```text
import type namespace.Type
from "vendor/package@requirement"
as LocalType;
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

114
examples/038-resolver-et-lockfile-examples.md Normal file
View File

@@ -0,0 +1,114 @@
# Exemples / DO-DON'T — Chapitre 38 — Resolver et lockfile
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
identity vendor/package
selector vendor/package@requirement
resolved instance vendor/package@MAJOR.MINOR.PATCH
```
### Exemple 2
```text
A -> foo/bar@^2.0
B -> foo/bar@^2.5
```
### Exemple 3
```text
A -> foo/bar@^2.0
B -> foo/bar@^3.0
```
### Exemple 4
```text
1. conservation des versions déjà verrouillées lorsqu'elles restent valides ;
2. minimisation du nombre d'instances distinctes ;
3. versions SemVer compatibles les plus élevées lorsqu'une nouvelle résolution est nécessaire.
```
### Exemple 5
```text
vendor/package@1.2.3
```
### Exemple 6
```text
saselang.lock
```
### Exemple 7
```text
project.manifest.toml
saselang.lock
```
### Exemple 8
```text
workspace.manifest.toml
saselang.lock
projects/.../project.manifest.toml
```
### Exemple 9
```text
identité vendor/package
selector/requirement d'origine
version exacte résolue
kind
source exacte
locator stable lorsque pertinent
checksum/intégrité lorsque pertinent
commit exact pour Git
features résolues
instances multi-version
graphe de dépendances
conditions target/features pertinentes
```
### Exemple 10
```text
normal
utilise le lock ;
le complète/corrige si nécessaire ;
n'upgrade pas gratuitement
locked
interdit toute modification du lock ;
échoue si le graphe demandé n'est pas reproductible
update
recherche volontairement de nouvelles versions compatibles
```
### Exemple 11
```text
resolved-package-instance
+ namespace
+ symbol
```
### Exemple 12
```text
acme/foo@1.0.0 :: data.Node
acme/foo@2.0.0 :: data.Node
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

88
examples/039-features-module-saselmod-et-compilation-conditionnelle-examples.md Normal file
View File

@@ -0,0 +1,88 @@
# Exemples / DO-DON'T — Chapitre 39 — Features, `module.saselmod` et compilation conditionnelle
> Document compagnon non normatif tant qu'une règle n'est pas explicitement référencée comme normative par le chapitre.
## Exemples actuellement présents dans le chapitre
### Exemple 1
```text
activer une dépendance optionnelle
activer un module
sélectionner une capacité/backend fonctionnel de library
contraindre d'autres features
```
### Exemple 2
```text
requires
conflicts
one-of
at-least-one
```
### Exemple 3
```text
namespace ...;
```
### Exemple 4
```text
doc ...
deprecated ...
forbid unsafe
requires feature ...
requires capability ...
requires target ...
```
### Exemple 5
```text
forbid unsafe
requires feature
requires capability
requires target
```
### Exemple 6
```text
ne produit jamais de valeur ;
ne peut jamais être utilisé comme expression ;
ne peut dépendre que d'informations déterminables à la compilation.
```
### Exemple 7
```text
des déclarations top-level complètes ;
des blocs d'implémentation dans le corps d'une callable.
```
### Exemple 8
```text
language version
compiler version
Core/SDK version
package identity/version
features actives
dépendances résolues
profile
artifact
target family
platform
architecture
ABI
endianness
pointer width
capabilities
```
## DO / DON'T / WHY / compiler error / edge cases
La couverture structurée de cette section sera enrichie au fur et à mesure de la fermeture des règles du chapitre. La migration `0.2.12` conserve volontairement les exemples historiques dans le chapitre afin de ne perdre aucun contexte normatif.

Some files were not shown because too many files have changed in this diff Show More