VITTE LIGHT — Guide utilisateur complet

0) Introduction — VITTE LIGHT

Vitte Light (abrégé VITL) est une déclinaison minimaliste du langage Vitte. L’objectif : offrir une syntaxe cohérente, des outils intégrés (formatage, analyse statique, tests, génération de doc) et un modèle mémoire prévisible, afin que débutants, développeurs intermédiaires et professionnels soient vite productifs — que ce soit pour un script d’atelier, un petit binaire livré à un client, ou un module embarqué via FFI dans une base C existante.

module app.main
import std.io

fn main() -> i32 {
  std.io::println("Bonjour Vitte Light")
  return 0
}

module app.main
import std.{io, cli, str}

fn main() -> i32 {
  let argv = cli::args()
  if str::len(argv) < 2 { io::eprintln("usage: app <nom>"); return 2 }
  io::println("Bonjour " + argv[1])
  return 0
}

# Formater
vitl fmt src/

# Analyser
vitl check src/

# Lancer les tests (dans les fichiers)
vitl test

# Générer doc depuis ///-commentaires
vitl doc src/ -o build/docs.txt

mon_projet/
  src/
    main.vitl        # module app.main
  build/             # artefacts (binaire, docs, bytecode)

1) Structure de projet — Guide complet

Une structure claire évite des heures perdues : on sait où créer un fichier, où trouver une fonctionnalité, où tombent les binaires. Cette section propose une arborescence de base puis des variantes (simple → complexe), des conventions de nommage, des exemples copier/coller (.gitignore, tâches build, CI), et des intégrations C (CMake/Meson).

1.1 Arborescence type minimale

/src   → code source principal (.vitl)
/libs  → bibliothèques natives C/FFI (.c, .so, .dll, .a)
/build → binaires, artefacts intermédiaires, bytecode (.vitbc)

mon_projet/
  src/
    main.vitl
    util/str.vitl
  libs/
    mylib.c
    mylib.a
  build/
    app        (binaire natif)
    app.vitbc  (bytecode)

1.2 Convention des modules

• Un fichier = un module.
• Chemin disque = nom de module (lisible et prédictible).
• Noms en snake.case pour modules/fichiers, CamelCase pour types.

Fichier : src/std/io.vitl
Contenu : module std.io

Fichier : src/app/http/client.vitl
Contenu : module app.http.client

Imports clairs : import std.io, import util.str. Évite les conflits, favorise la réutilisation.

1.3 Variantes d’organisation (selon la taille)

mon_projet/
  src/main.vitl
  src/util/print.vitl
  build/

mon_projet/
  src/app/main.vitl
  src/app/cli/args.vitl
  src/std/extra/time.vitl
  src/util/fs.vitl
  libs/fast.c
  build/{debug,release,docs}

mon_projet/
  src/
    app/main.vitl
    app/sub/feature.vitl
    core/error.vitl
    core/config.vitl
    net/http.vitl
    net/tcp.vitl
    std/extra/...
  tests/
    test_core.vitl
    test_net.vitl
  libs/
    sqlite/sqlite3.c
    wrapper/foo.c
  build/
    debug/
    release/
    docs/
  scripts/
    build.sh
    release.sh
  docs/
    README.md
    CHANGELOG.md

1.4 Rôles des dossiers (rappel express)

• /src : code VITL uniquement (modules, types, fonctions, tests intégrés).
• /libs : code C/C++ enveloppé côté C (shim) pour exposer une API C stable.
• /build : non versionné ; binaires, .vitbc, docs générées, artefacts temporaires.
• /tests (optionnel) : scénarios et jeux de données.
• /scripts (optionnel) : tâches build/release reproductibles.
• /docs (optionnel) : guides, captures, changelog, spécifications.

1.5 Conventions de nommage

• Modules/fichiers : snake.case (net/http.vitl → module net.http).
• Types : CamelCase (struct HttpClient).
• Fonctions/variables : snake_case (fn read_config()).
• Tests : test "nom explicite du comportement".

1.6 Chemins & portabilité (Linux/macOS/Windows)

• Utilisez des chemins relatifs au projet (évite les surprises en CI).
• Évitez de coder en dur \\ ou / : centralisez la logique de chemins si nécessaire.
• Stockez les fichiers de test dans tests/data/ et adressez-les via std.fs depuis la racine.

1.7 Tests : où les placer ?

• Petit projet : tests à la fin de chaque fichier.
• Projet moyen/complexe : combiner tests intégrés + scénarios dans /tests.

src/core/math.vitl
  ... code ...
  test "somme de base" { assert(add(1,2) == 3) }

tests/test_math.vitl
  ... scénarios plus riches, I/O, golden files ...

1.8 Documentation générée

Documentez vos APIs avec /// en tête d’éléments publics, puis générez avec vitl doc src/ -o build/docs.txt. Conservez les docs “métier” plus longues dans /docs.

1.9 Sorties de build (organisation)

/build/
  debug/     → binaires -O0 -g (débogage)
  release/   → binaires -O3 (livraison)
  docs/      → doc générée (ex. docs.txt)
  *.vitbc    → bytecode (exécution VM)

1.10 Fichier .gitignore (copier/coller)

# VITL
/build/
*.vitbc

# OS
.DS_Store
Thumbs.db

# Éditeurs/IDE
.vscode/
.idea/
*.iml

# Logs/temp
*.log
.tmp/
.cache/

1.11 Tâches build pratiques

# scripts/build.sh
set -euo pipefail
mkdir -p build/release
vitl fmt src/
vitl check src/
vitl build -O3 -o build/release/app src/app/main.vitl
echo "OK → build/release/app"

# scripts/build.ps1
$ErrorActionPreference = "Stop"
New-Item -ItemType Directory -Force -Path build/release | Out-Null
vitl fmt src/
vitl check src/
vitl build -O3 -o build/release/app.exe src/app/main.vitl
Write-Host "OK → build/release/app.exe"

1.12 Intégration CI (GitHub Actions minimal)

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install VITL
        run: |
          mkdir -p ~/bin
          curl -L <URL_VITL_LINUX> -o ~/bin/vitl
          chmod +x ~/bin/vitl
          echo "$HOME/bin" >> $GITHUB_PATH
      - name: Format & Check
        run: |
          vitl fmt src/
          vitl check src/
      - name: Tests
        run: vitl test
      - name: Build (release)
        run: vitl build -O3 -o build/release/app src/app/main.vitl
      - name: Upload artefacts
        uses: actions/upload-artifact@v4
        with:
          name: app-linux
          path: build/release/app

Adaptez l’étape “Install VITL” à votre source de binaire (URL/paquet interne).

1.13 Intégration d’une lib C (FFI) — CMake

# libs/CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(vitl_ffi C)
add_library(foo STATIC foo.c)
target_include_directories(foo PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})

# Construire la lib puis lier côté VITL
mkdir -p libs/build && cd libs/build
cmake ..
cmake --build . --config Release
# Ensuite, côté VITL :
vitl build -O2 -L libs/build -lfoo -o build/app src/main.vitl

1.14 Intégration d’une lib C (FFI) — Meson

# libs/meson.build
project('vitl_ffi', 'c')
libfoo = static_library('foo', 'foo.c', include_directories: include_directories('.'))

# Build Meson/Ninja
meson setup libs/build libs
meson compile -C libs/build
# Puis lier lors du build VITL :
vitl build -O2 -L libs/build -lfoo -o build/app src/main.vitl

1.15 Packaging & release

• Générez le binaire release/ (-O3) pour chaque OS visé.
• Ajoutez un README court par plateforme : commande, options, exemples.
• Incluez LICENSE, CHANGELOG.md et un hash (SHA256) des binaires.
• Option : archivez app + fichiers d’exemple (examples/).

1.16 Versionning & docs projet

• CHANGELOG.md (Keep a Changelog : Added/Changed/Fixed/Removed).
• README.md : but, installation, quick start, table des commandes.
• Tagguez vos versions (tags Git) ; automatisez un brouillon de release en CI.

1.17 Fichiers de configuration (exemples)

# Mon Projet VITL
But : une ligne claire ici.

## Installation
- Télécharger le binaire.
- Ajouter au PATH.

## Utilisation
\`\`\`sh
vitl --help
\`\`\`

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

2) Outils en ligne de commande — Guide ultra-complet

2.1 Exécution immédiate (VM/JIT)

# Lancer un fichier
vitl run src/main.vitl

# Passer des arguments utilisateur au programme (utilisez -- pour séparer)
vitl run src/cat.vitl -- README.md

# Exécuter plusieurs fichiers (point d’entrée = premier fichier avec fn main)
vitl run src/app/main.vitl src/util/str.vitl

• Quand l’utiliser : démo, TDD rapide, scripts éphémères, validation CI sans build natif.
• Bon à savoir : la VM applique les mêmes vérifications que le build (types, imports, sécurité).

2.2 Compilation en exécutable natif

# Build simple (optimisation par défaut -O2)
vitl build -o build/app src/main.vitl

# Profils typiques
vitl build -O0 -g -o build/debug/app    src/main.vitl   # Débogage (rapide à compiler)
vitl build -O3    -o build/release/app  src/main.vitl   # Livraison (perf max)

# Émettre des artefacts intermédiaires
vitl build --emit-ir       -o build/app src/main.vitl   # IR lisible
vitl build --emit-bytecode -o build/app src/main.vitl   # Bytecode VM (.vitbc)

2.3 Formateur, analyseur, tests, doc

# Formater tout le code (à intégrer en pre-commit)
vitl fmt src/

# Analyse statique (imports manquants, types, règles de base)
vitl check src/

# Tests intégrés (cherche et exécute tous les blocs `test "..." {}`)
vitl test

# Documentation à partir des commentaires /// en tête d’API publiques
vitl doc src/ -o build/docs.txt

2.4 Lier des bibliothèques C (FFI)

# Fichiers de shim C compilés séparément dans libs/
# Lier une lib partagée ou statique pendant le build
vitl build -O2 -L libs -lfoo -o build/app src/main.vitl

# Définir un rpath pour retrouver les .so/.dylib à l’exécution (Linux/macOS)
vitl build -O2 -L libs -lfoo -Wl,-rpath,./libs -o build/app src/main.vitl

• -L : ajoute un chemin de recherche des bibliothèques.
• -lfoo : lie la bibliothèque libfoo.{so,dylib,a}.
• Astuce : conservez un shim C plat (types stables, ownership clair) pour un FFI robuste.

2.5 Exemples concrets (sessions)

# Hello World (VM puis binaire)
vitl run   src/main.vitl
vitl build -O2 -o build/hello src/main.vitl
./build/hello

# Programme CLI avec arguments et codes d’erreur
vitl run src/cat.vitl -- data.txt     # 0 si succès, 2 usage, 3 I/O
vitl build -O2 -o build/cat src/cat.vitl
./build/cat data.txt
echo $?   # vérifie le code de sortie

# Pipeline CI local minimal (bash)
set -euo pipefail
vitl fmt src/
vitl check src/
vitl test
vitl build -O3 -o build/release/app src/app/main.vitl

2.6 Débogage & diagnostics

• Compilez avec -g pour obtenir des backtraces plus utiles.
• En VM (vitl run), les messages d’erreur incluent le module et la ligne fautive.
• Utilisez --emit-ir/--emit-bytecode pour comprendre ce que “voit” le compilateur.

2.7 Organisation des sorties

mkdir -p build/{debug,release,docs}
vitl build -O0 -g -o build/debug/app   src/app/main.vitl
vitl build -O3    -o build/release/app src/app/main.vitl
vitl doc src/ -o build/docs/api.txt

2.8 Bonnes pratiques (tous niveaux)

• Débutant : vitl run + vitl fmt. Gardez un seul fichier main.vitl au début.
• Intermédiaire : ajoutez vitl check, factorisez en modules, commencez à tester (vitl test).
• Pro : CI (fmt/check/test/build), doc générée, profilage simple, FFI maîtrisé (règles d’ownership).

2.9 Problèmes fréquents & solutions

2.10 Table de référence rapide

Résumé — Utilisez run pour explorer, build pour livrer. Automatisez fmt/check/test en CI. Inspectez avec --emit-ir/--emit-bytecode. Pour le FFI, liez proprement avec -L/-l et un shim C clair.

3) Syntaxe : découverte progressive

3.0 Votre premier “mini-lab” (2 minutes)

1. Créez src/play.vitl avec le contenu ci-dessous.
2. Lancez vitl run src/play.vitl et observez la sortie.

module app.play
import std.io

fn main() -> i32 {
  let msg = "Bonjour"        // immuable
  let mut n = 1              // mutable
  n = n + 1
  std.io::println(msg + " n=" + n.to_string())
  return 0
}
// Sortie attendue : Bonjour n=2

3.1 Commentaires & documentation

Les commentaires expliquent pourquoi (pas juste “ce que ça fait”). Les commentaires de doc (///) apparaissent dans vitl doc.

// Ligne unique
/* Bloc multi-lignes */

/// Additionne deux entiers (sans débordement contrôlé)
fn add(a:i32, b:i32) -> i32 { return a + b }

3.2 Nommage lisible (conseils débutant)

• Variables/fonctions en snake_case, types en CamelCase.
• Un bon nom évite des commentaires : préférez max_retries à mr.

let user_name = "Alice"
struct Point2D { x:f64, y:f64 }

3.3 Types de base & littéraux

Pas besoin de tout retenir : l’éditeur et les erreurs vous guident.

• Entiers : i32, i64 (ex. 42, 0xFF, 0b1010)
• Flottants : f64 (ex. 3.14, 2.0e-3)
• Booléens : true, false
• Caractères : 'a', '\n'
• Chaînes UTF-8 : "..." ou brutes r"..."

const PI:f64 = 3.14159
let ok:bool = true
let hex:i32 = 0xCAFE

3.4 Variables, constantes, mutabilité

Immuable par défaut = code plus sûr. Ajoutez mut uniquement où nécessaire.

const MAX_RETRY:i32 = 3         // constante
let count:i32 = 0               // immuable
let mut total:f64 = 0.0         // mutable
total = total + 1.5

// Inférence de type quand c'est clair
let message = "Salut"  // :str

3.5 Opérateurs & conversions

VITL évite les conversions implicites “magiques”. Convertissez avec as (numérique) ou to_string() (texte).

let n:i32 = 3
let x:f64 = 0.5
let y = (n as f64) + x          // cast requis

std.io::println("n=" + n.to_string())  // convertir avant concaténation

3.6 Chaînes : str vs String (images mentales)

• str : “post-it” vers un texte (on ne le modifie pas).
• String : “carnet” qui vous appartient (on peut écrire dedans).

let s:str = "abc"
let mut buf = String::from("abc")
buf.push("d")            // "abcd"
std.io::println(buf)

3.7 Collections, slices & boucles

Les indices sont vérifiés : une erreur claire vaut mieux qu’un crash silencieux.

let mut v:[i32] = [1,2,3]
v.push(4)
for x in &v { std.io::println(x.to_string()) }
let third = v[2]   // panique si hors bornes → message explicite

3.8 Contrôle de flux (recettes courantes)

// if / else
if y > 0.0 { std.io::println("positif") } else { std.io::println("non positif") }

// while
let mut i = 0
while i < 3 { std.io::println(i.to_string()); i = i + 1 }

// for + intervalles
for k in 0..3  { std.io::println(k.to_string()) }   // 0,1,2
for k in 0..=3 { std.io::println(k.to_string()) }   // 0..3 inclus

// break / continue
for n in 0..10 {
  if n == 5 { break }
  if n % 2 == 0 { continue }
  std.io::println(n.to_string())
}

3.9 Fonctions (penser “boîte noire”)

Une fonction prend des entrées, produit des sorties, et peut signaler un échec avec Result. VITL n’infère pas le type de retour : écrivez-le.

// Paramètres nommés et type de retour explicite
fn square(x:i32) -> i32 { return x * x }

// Valeur ou erreur (Result)
fn div(a:i32, b:i32) -> Result<i32, str> {
  if b == 0 { return Result::Err("division par zéro") }
  return Result::Ok(a / b)
}

// Passer par référence pour éviter une copie lourde
fn print_len(s:&String) -> () {
  std.io::println(s.len().to_string())
}

3.10 Erreurs : Result, Option et opérateur ?

Result<T,E> représente un succès (Ok(T)) ou un échec (Err(E)). L’opérateur ? “bulle” l’erreur au dessus : s’il y a Err, la fonction courante s’arrête et renvoie cette erreur.

// I/O : propage l’erreur si le fichier est introuvable/illisible
fn load(path:str) -> Result<String, str> {
  let txt = std.fs::read_to_string(path)?   // <— propage
  return Result::Ok(txt)
}

// Valeur optionnelle (présence/absence)
match std.cli::env("HOME") {
  Some(h) => std.io::println(h),
  None    => std.io::eprintln("HOME non défini"),
}

3.11 match exhaustif & enums

match impose de couvrir tous les cas (soit explicitement, soit via _ pour “autre”).

enum Status { Ok, Err(str) }

fn report(s:Status) -> () {
  match s {
    Status::Ok     => std.io::println("ok"),
    Status::Err(e) => std.io::eprintln("erreur:" + e),
  }
}

3.12 Structs, méthodes (impl) et récepteurs &self

Les méthodes se définissent dans un bloc impl. &self signifie “emprunter l’objet sans le copier”.

struct Vec2 { x:f64, y:f64 }

impl Vec2 {
  fn norm(&self) -> f64 { return (self.x*self.x + self.y*self.y).sqrt() }
  fn dot(&self, o:Vec2) -> f64 { return self.x*o.x + self.y*o.y }
}

fn main() -> i32 {
  let v = Vec2 { x:3.0, y:4.0 }
  std.io::println(v.norm().to_string())  // 5
  return 0
}

3.13 Modules & imports (organisation du code)

Le chemin disque détermine le nom de module. Gardez cette règle et vous saurez toujours “où vit quoi”.

// Fichier : src/util/str.vitl
module util.str
// ... API ...

// Fichier : src/app/main.vitl
module app.main
import std.{io, fs}
import util.str

fn main()->i32 {
  std.io::println("Ready")
  return 0
}

3.14 Génériques (usage simple)

La version Light supporte des génériques “légers” pour des cas typiques (fonctions d’ordre supérieur, conteneurs simples).

// Exécuter une fonction et mesurer son temps
fn timed<F>(label:str, f:F) -> ()
where F: fn()->() {
  let t0 = std.time::now()
  f()
  std.io::println(label + ":" + (std.time::now()-t0).to_string() + " ms")
}

3.15 Formats d’entrées/sorties (console & fichiers)

// Console
std.io::print("sans retour")
std.io::println("avec retour")
std.io::eprintln("erreur: usage invalide")

// Fichiers
_ = std.fs::write_string("out.txt", "ok\n")?
let txt = std.fs::read_to_string("out.txt")?

3.16 Bonnes pratiques (tous niveaux)

• Déclarez les types de retour des fonctions (lisibilité, erreurs plus claires).
• Préférez Result + ? à des codes sentinelles.
• Validez tôt l’entrée (fail-fast) et produisez des messages d’erreur utiles.
• Séparez vos modules par responsabilité (util, io, app, …).

3.17 Pièges fréquents (et correctifs)

// Mauvais
module app.main
fn main()->i32 { std.io::pritnln("hi"); return 0 }

// Correct
module app.main
import std.io
fn main()->i32 { std.io::println("hi"); return 0 }

// Mauvais
let n:i32 = 3
std.io::println("n=" + n)

// Correct
std.io::println("n=" + n.to_string())

3.18 Exercices guidés (à vous de jouer)

1. Convertisseur : lisez un nombre depuis la ligne de commande et affichez son double (gérez l’erreur si l’argument manque).
2. Concat : créez une String, ajoutez-y trois morceaux (push), affichez le résultat.
3. Vec2 : reprenez la struct Vec2, ajoutez une méthode scale(&mut self, k:f64), testez-la.

4) Premiers exemples — ultra détaillés (spécial débutants)

4.0 Avant de commencer

1. Créez un dossier de travail (ex. vitte-light-demo/).
2. À l’intérieur, créez src/ et build/.
3. Chaque exemple ci-dessous suppose que les fichiers sont dans src/.

Commandes clés : vitl run <fichier.vitl> (exécution rapide) · vitl build -O2 -o build/app <fichier.vitl> (binaire natif) · vitl fmt src/ (formateur) · vitl test (tests intégrés).

4.1 Débutant → programme minimal (Hello + variables + concat)

// src/main.vitl
module app.main
import std.io

fn main() -> i32 {
  let msg = "Bonjour Vitte Light"
  let mut n = 1
  n = n + 1
  std.io::println(msg + " · n=" + n.to_string())
  return 0
}

Exécution : vitl run src/main.vitl

Sortie attendue : Bonjour Vitte Light · n=2

// A) Bonjour personnalisé via variable
module app.hello
import std.io
fn main()->i32 {
  let name = "Alice"
  std.io::println("Bonjour, " + name)
  return 0
}

// B) Codes de sortie (1 = erreur générique)
module app.exit
import std.io
fn main()->i32 {
  if 2 + 2 != 4 {
    std.io::eprintln("arithmétique cassée")
    return 1
  }
  return 0
}

Tests (mini TDD)

// Ajoutez à la fin de src/main.vitl :
test "arithmétique de base" { assert(2 + 2 == 4) }

Lancez : vitl test → affichera les tests réussis.

4.2 Débutant+ → lecture de fichier (usage & erreurs)

// src/cat.vitl
module app.cat
import std.{fs, io, cli, str}

fn main() -> i32 {
  let argv = cli::args()
  if str::len(argv) < 2 {
    io::eprintln("usage: cat <fichier>")
    return 2 // erreur d'usage CLI
  }
  let path = argv[1]
  if !fs::exists(path) {
    io::eprintln("introuvable: " + path)
    return 3 // erreur I/O
  }
  let contenu = fs::read_to_string(path)? // propage l'erreur I/O si échec
  io::print(contenu)
  return 0
}

Exécution : vitl run src/cat.vitl -- data.txt

• OK → affiche le contenu.
• Sans argument → sortie 2 (erreur d’usage).
• Fichier manquant → sortie 3 (erreur I/O).

// A) Taille en octets
module app.size
import std.{fs, io}
fn main()->i32 {
  let bytes = fs::read("data.bin")?
  io::println("taille=" + bytes.len().to_string() + " octets")
  return 0
}

// B) Multi-fichiers (ignore les manquants)
module app.cat_multi
import std.{fs, io, cli, str}
fn main()->i32 {
  let a = cli::args()
  if str::len(a) < 2 { io::eprintln("usage: cat_multi <f1> [<f2>...]"); return 2 }
  for i in 1..str::len(a) {
    let p = a[i]
    if !fs::exists(p) { io::eprintln("skip: " + p); continue }
    io::print(fs::read_to_string(p)?)
  }
  return 0
}

// C) Chronométrage simple
module app.timed_cat
import std.{fs, io, cli, str, time}
fn main()->i32 {
  let a = cli::args()
  if str::len(a) != 2 { io::eprintln("usage: timed_cat <f>"); return 2 }
  let t0 = time::now()
  _ = fs::read_to_string(a[1])?
  io::println("ms=" + (time::now()-t0).to_string())
  return 0
}

let path = argv[1]
if !fs::exists(path) {
  io::eprintln("E2001: fichier introuvable → " + path)
  io::eprintln("Astuce: lancez depuis la racine du projet ou passez un chemin absolu.")
  return 3
}

Tests

// Exemple de test "attendu en erreur"
test "cat sans argument renvoie 2" {
  // pseudo-test illustratif : dans une vraie CI, on lance le binaire et on vérifie le code
  assert(2 == 2)
}

4.3 Débutant++ → calculs et types (struct, méthodes, tests)

// src/geom.vitl
module app.geom
import std.{io, math}

struct Vec2 { x: f64, y: f64 }

impl Vec2 {
  fn norm(&self) -> f64 { return (self.x*self.x + self.y*self.y).sqrt() }
  fn dot(&self, o: Vec2) -> f64 { return self.x*o.x + self.y*o.y }
}

fn main() -> i32 {
  let v = Vec2 { x: 3.0, y: 4.0 }
  io::println(v.norm().to_string()) // 5
  return 0
}

// Tests intégrés
test "norme 3-4-5" {
  let v = Vec2 { x:3.0, y:4.0 }
  assert(v.norm() == 5.0)
}
test "produit scalaire orthogonal" {
  let a = Vec2 { x:1.0, y:0.0 }
  let b = Vec2 { x:0.0, y:1.0 }
  assert(a.dot(b) == 0.0)
}

Exécution : vitl run src/geom.vitl → affiche 5

Tests : vitl test

// src/geom_cli.vitl
module app.geom_cli
import std.{io, cli, str}

struct Vec2 { x:f64, y:f64 }
impl Vec2 { fn norm(&self)->f64 { return (self.x*self.x + self.y*self.y).sqrt() } }

fn parse_f64(s:str) -> Result<f64,str> { return str::to_float(s) }

fn main()->i32 {
  let a = cli::args()
  if str::len(a) != 3 { io::eprintln("usage: geom_cli <x> <y>"); return 2 }
  let x = parse_f64(a[1])?
  let y = parse_f64(a[2])?
  let v = Vec2 { x:x, y:y }
  io::println(v.norm().to_string())
  return 0
}

4.4 Mini-projets guidés (copier / adapter)

4.4.1 Greeter (salut personnalisé + validation)

// src/greeter.vitl
module app.greeter
import std.{io, cli, str}

fn main()->i32 {
  let a = cli::args()
  if str::len(a) != 2 { io::eprintln("usage: greeter <nom>"); return 2 }
  let name = a[1]
  if str::len(name) == 0 { io::eprintln("nom vide"); return 2 }
  io::println("Bonjour, " + name)
  return 0
}

Test manuel : vitl run src/greeter.vitl -- Alice → Bonjour, Alice

4.4.2 Compteur de lignes (LC) avec messages clairs

// src/wc_lines.vitl
module app.wc_lines
import std.{io, fs, cli, str}

fn main()->i32 {
  let a = cli::args()
  if str::len(a) != 2 { io::eprintln("usage: wc_lines <fichier>"); return 2 }
  let p = a[1]
  if !fs::exists(p) { io::eprintln("introuvable: " + p); return 3 }
  let txt = fs::read_to_string(p)?
  // Compte naïf des lignes : nombre de '\n' + 1 si non vide
  let mut n:i64 = 0
  for ch in &txt {
    if ch == '\n' { n = n + 1 }
  }
  if str::len(txt) > 0 && txt[str::len(txt)-1] != '\n' { n = n + 1 }
  io::println(n.to_string())
  return 0
}

4.4.3 Mesure de temps & micro-bench

// src/bench.vitl
module app.bench
import std.{io, time}

fn heavy()->() {
  let mut s:i64 = 0
  for i in 0..100000 { s = s + i }
  io::println("acc=" + s.to_string())
}

fn main()->i32 {
  let t0 = time::now()
  heavy()
  io::println("ms=" + (time::now() - t0).to_string())
  return 0
}

4.5 Gérer les erreurs proprement (Result, Option, messages)

// src/config_load.vitl
module app.config_load
import std.{io, fs, str}

fn load_threshold(path:str) -> Result<i64, str> {
  if !fs::exists(path) { return Result::Err("absent: " + path) }
  let s = fs::read_to_string(path)?
  // Nettoie un éventuel retour chariot / fin de ligne
  let cleaned = str::replace(str::replace(s, "\r", ""), "\n", "")
  return str::to_int(cleaned)
}

fn main()->i32 {
  match load_threshold("threshold.txt") {
    Result::Ok(v) => { io::println("seuil=" + v.to_string()); return 0 }
    Result::Err(e) => { io::eprintln("E: " + e); return 3 }
  }
}

4.6 Modèle de projet minimal (à répliquer)

mon_projet/
  src/
    main.vitl         // point d'entrée
    greeter.vitl      // sous-outil
    wc_lines.vitl     // sous-outil
  build/              // binaires

// src/main.vitl
module app.main
import std.io

fn main()->i32 {
  std.io::println("Projet prêt. Voir src/greeter.vitl et src/wc_lines.vitl")
  return 0
}

Formatez : vitl fmt src/ · Testez : vitl test · Compilez : vitl build -O2 -o build/app src/main.vitl

4.7 Checklist mini-projet (qualité débutant → pro)

• Un main.vitl exécutable en une commande.
• Messages d’erreur explicites (usage, I/O).
• Au moins 1–2 tests intégrés par fichier.
• Imports précis et formateur (vitl fmt) exécuté.
• Codes de sortie stables : 0 (OK) · 1 (panic) · 2 (usage) · 3 (I/O) · 4 (FFI).

5) Mémoire et sécurité — ultra-guide débutant

5.1 Pourquoi parler de mémoire ?

Un programme manipule des valeurs (nombres, textes, tableaux…). Ces valeurs occupent de la mémoire. Deux grands risques : utiliser de la mémoire libérée (crashes, comportements bizarres) et oublier de libérer (fuites). VITL vous aide : il libère automatiquement quand plus personne n’utilise la donnée (comptage de références), et il encadre les appels « bas niveau » via FFI C.

5.2 Modèle mental (débutant)

• Valeur simple : « je possède la donnée » (ex. un i32 ou une String locale).
• Partage : « nous possédons à plusieurs » → enrobez la donnée dans un Rc<T>.
• Lien de retour (parent ↔ enfant) : pour briser le cycle, le lien « faible » se fait en Weak<T>.
• FFI : les chaînes C sont null-terminées ; on passe une CString et on respecte qui alloue/libère.

5.3 Références comptées : Rc<T>

import std.io

fn main() -> i32 {
  let a = Rc<i32>::new(42) // 1 détenteur fort
  let b = a.clone()        // 2 détenteurs forts
  std.io::println("ok: " + (*b).to_string())
  a.drop()                 // 1 détenteur fort
  b.drop()                 // 0 → libération automatique
  return 0
}

Quand utiliser : configuration partagée, cache simple, nœuds d’arbre, tables consultées par plusieurs modules.

5.4 Lien faible : Weak<T> pour briser les cycles

Exemple classique : un parent garde ses enfants (fort), chaque enfant garde un lien vers son parent (faible).

// src/tree.vitl
module app.tree
import std.{io, str}

struct Node {
  name: String,
  parent: Weak<Node>,      // lien FAIBLE
  children: [Rc<Node>],     // liens FORTS
}

fn Node::new(name:str) -> Rc<Node> {
  return Rc<Node>::new(Node { name: String::from(name), parent: Weak<Node>::new(), children: [] })
}

fn Node::add_child(this:&Rc<Node>, child:Rc<Node>) -> () {
  // le parent garde fort
  this.children.push(child.clone())
  // l'enfant garde FAIBLE vers le parent
  let w = Rc::downgrade(this)       // Rc -> Weak
  child.parent.set(w)               // (API imagée : associer le Weak)
}

fn main()->i32 {
  let root = Node::new("root")
  let a = Node::new("A")
  Node::add_child(&root, a)
  io::println("children=" + root.children.len().to_string())
  // On peut faire "upgrade" d'un Weak en Rc pour utiliser temporairement le parent
  match root.children[0].parent.upgrade() {
    Some(p) => io::println("parent de A = " + p.name),
    None    => io::println("parent libéré"),
  }
  return 0
}

Idée : si le parent meurt, le Weak devient « vide » (impossible à upgrade()), donc pas de fuite.

5.5 Chaînes : str (vue) vs String (tampon possédé)

• str : lecture sans copie (immuable). Idéal pour paramètres d’API.
• String : vous possédez et pouvez modifier (ajouter, tronquer).

let s:str = "abc"
let mut buf = String::from("abc")
buf.push("d") // "abcd"
std.io::println(buf)

5.6 Collections & slices (éviter les copies coûteuses)

import std.{io, vec}
let mut v:[i32] = vec::with_capacity(16) // évite les réallocations
v.push(1); v.push(2); v.push(3)
for x in &v { io::println(x.to_string()) } // itération par référence (pas de copie)
let third = v[2] // panique si hors bornes

5.7 FFI C en sécurité (pont contrôlé)

Le C attend des *const char terminés par nul et ne comprend pas les String de VITL. Convertissez toujours via CString. Décidez qui libère quoi.

// Déclaration (ex.)
extern "C" { fn puts(msg:*const char) -> i32 }

fn c_puts(s:str) -> Result<(), str> {
  let c = std.c::CString::from_str(s)?   // valide l'absence de nul
  unsafe { _ = puts(c.as_ptr()) }        // frontière unsafe MINIMALE
  return Result::Ok(())
}

• Frontière claire : convertir, vérifier, appeler C, sortir du unsafe rapidement.
• Ownership documenté : si le C alloue, fournissez une fonction de libération claire (free_c_buffer(ptr)), et appelez-la côté VITL.

5.8 Libération automatique : quand ?

• Variable locale : à la fin du bloc où elle est déclarée.
• Rc : quand le compteur de références fortes retombe à zéro.
• Ressource externe (descripteur, handle C) : vous appelez explicitement la fonction de fermeture/libération prévue.

5.9 Petites recettes « zéro fuite »

• Graphes : liens « avant » en Rc, liens « retour » en Weak.
• Caches : valeurs en Rc, index clé → Weak si vous voulez permettre l’éviction automatique.
• FFI : 1) construire CString ; 2) appeler dans un petit unsafe ; 3) libérer ce que le C a alloué, via la bonne fonction.

5.10 Diagnostic & debug

• Construire en debug : vitl build -O0 -g -o build/app src/main.vitl pour des messages plus précis.
• Messages clairs : incluez le chemin, l’action, la cause humaine (« Astuce : … »).
• Imprimez les tailles et compteurs (ex. children.len()) pour vérifier votre modèle.

// Message enrichi
let path = "data/config.txt"
if !std.fs::exists(path) {
  std.io::eprintln("E2001: fichier introuvable → " + path)
  std.io::eprintln("Astuce: lancez depuis la racine du projet ou passez un chemin absolu.")
  return 3
}

5.11 Mini-FAQ (débutant)

5.12 Exemples « prêt à copier »

a) Partage simple sans cycle

// src/shared_config.vitl
module app.shared_config
import std.{io}

struct Config { name:String, retries:i32 }

fn main()->i32 {
  let cfg = Rc<Config>::new(Config { name:String::from("demo"), retries:3 })
  let worker1 = cfg.clone()
  let worker2 = cfg.clone()
  io::println("retries=" + worker2.retries.to_string())
  // À la fin, worker1, worker2 et cfg tombent à 0 → libération
  return 0
}

b) Encapsuler une ressource C

// src/ffi_wrapper.vitl
module app.ffi_wrapper
import std.{io, c}

// C opaque
extern "C" {
  fn obj_create() -> *mut void
  fn obj_destroy(p:*mut void) -> void
  fn obj_set_name(p:*mut void, name:*const char) -> i32
}

struct Obj { handle:*mut void }

fn Obj::new() -> Result<Obj, str> {
  let h = unsafe { obj_create() }
  if h == std.ptr::null_mut() { return Result::Err("ffi: create failed") }
  return Result::Ok(Obj{ handle:h })
}

fn Obj::set_name(&mut self, name:str) -> Result<(), str> {
  let cname = c::CString::from_str(name)?
  let rc = unsafe { obj_set_name(self.handle, cname.as_ptr()) }
  if rc != 0 { return Result::Err("ffi: set_name failed") }
  return Result::Ok(())
}

fn Obj::close(&mut self) -> () {
  if self.handle != std.ptr::null_mut() {
    unsafe { obj_destroy(self.handle) }
    self.handle = std.ptr::null_mut()
  }
}

fn main()->i32 {
  let mut o = Obj::new()?
  _ = o.set_name("demo")?
  o.close() // libération explicite
  return 0
}

5.13 Récapitulatif débutant

6) Gestion des erreurs — ultra-guide débutant

6.1 Pourquoi gérer les erreurs ?

Une bonne gestion d’erreurs rend votre outil prévisible et aimable : message clair, action proposée, code de sortie stable (pour les scripts/CI). VITL favorise l’approche explicite : on retourne un Result (ou Option) au lieu de masquer l’échec.

6.2 Le type Result<T,E> (base)

import std.{io, fs}

// Lecture de fichier : renvoie le texte ou une erreur (str)
fn read_cfg(path: str) -> Result<str, str> {
  if !fs::exists(path) {
    return Result::Err("absent: " + path)
  }
  let txt = fs::read_to_string(path)?   // propage l'erreur I/O si lecture échoue
  return Result::Ok(txt)
}

// Consommation : pattern matching
fn main() -> i32 {
  match read_cfg("config.txt") {
    Result::Ok(txt) => io::println(txt),
    Result::Err(e)  => { io::eprintln("E: " + e); return 3 }
  }
  return 0
}

Astuce — Commencez par une version « simple » où E est une chaîne str. Plus tard, passez à un type d’erreur structuré (cf. §6.9).

6.3 L’opérateur ? (propagation automatique)

? ne marche que dans une fonction qui retourne un Result<...>. Si l’expression à droite retourne Err, la fonction renvoie immédiatement cette erreur.

import std.{fs}

fn load_or_err(path: str) -> Result<str, str> {
  // Vérif claire + propagation compacte
  if !fs::exists(path) { return Result::Err("introuvable: " + path) }
  let txt = fs::read_to_string(path)?  // <= ici `?` propage l'erreur I/O
  return Result::Ok(txt)
}

6.4 Option<T> : absence de valeur ≠ erreur

import std.{io, cli}

fn print_home() -> () {
  match cli::env("HOME") {
    Some(h) => io::println(h),
    None    => io::eprintln("HOME non défini")
  }
}

Utilisez Option quand l’absence est attendue (ex. variable d’environnement facultative). Utilisez Result quand c’est une erreur.

6.5 Messages clairs : quoi / où / comment agir

// Mauvais : vague
io::eprintln("échec")

// Meilleur : contexte + astuce
io::eprintln("E2001: fichier introuvable → " + path)
io::eprintln("Astuce: lancez depuis la racine du projet ou passez un chemin absolu.")

6.6 Codes de sortie (stables)

• 0 succès
• 1 erreur générique / panic
• 2 erreur d’usage CLI (arguments invalides/manquants)
• 3 erreurs I/O (fichiers, permissions, disque)
• 4 erreurs FFI (appel C, contrat ABI)

6.7 Schéma recommandé pour main()

import std.{io, str, cli, fs}

// 1) "run" fait le travail et renvoie Result
fn run() -> Result<(), str> {
  let args = cli::args()
  if str::len(args) < 2 {
    return Result::Err("USAGE: app <fichier> (code 2)")
  }
  let path = args[1]
  if !fs::exists(path) { return Result::Err("E2001: absent → " + path) }
  io::print(fs::read_to_string(path)?)  // ? propage l'I/O
  return Result::Ok(())
}

// 2) "main" mappe proprement vers un code de sortie
fn main() -> i32 {
  match run() {
    Result::Ok(()) => return 0,
    Result::Err(msg) => {
      io::eprintln(msg)
      // Petite heuristique pour l'exemple :
      if str::find(msg, "USAGE:") != -1 { return 2 }
      if str::find(msg, "E2001") != -1 { return 3 }
      return 1
    }
  }
}

6.8 Validation d’entrée (avant l’I/O)

import std.{io, str}

fn parse_port(s: str) -> Result<i32, str> {
  match str::to_int(s) {
    Result::Ok(n) => {
      if n < 1 || n > 65535 { return Result::Err("port hors plage (1..65535)") }
      return Result::Ok(n as i32)
    }
    Result::Err(_) => return Result::Err("port invalide: " + s)
  }
}

6.9 Aller plus loin : erreurs structurées

Pour les applis plus grandes, définissez un type d’erreur unique. Exemple avec un enum et un to_msg() :

import std.{io, fs, str}

enum AppErr {
  Usage(str),   // USAGE/validation
  Io(str),      // fichiers/disque
  Parse(str),   // conversion/format
  Ffi(str),     // pont C
  Other(str),
}

fn err_usage(m:str) -> AppErr { return AppErr::Usage(m) }
fn err_io(m:str)    -> AppErr { return AppErr::Io(m) }
fn err_parse(m:str) -> AppErr { return AppErr::Parse(m) }
fn err_ffi(m:str)   -> AppErr { return AppErr::Ffi(m) }
fn err_other(m:str) -> AppErr { return AppErr::Other(m) }

fn to_msg(e:AppErr) -> str {
  match e {
    AppErr::Usage(m) => return "USAGE: " + m,
    AppErr::Io(m)    => return "I/O: " + m,
    AppErr::Parse(m) => return "PARSE: " + m,
    AppErr::Ffi(m)   => return "FFI: " + m,
    AppErr::Other(m) => return "ERR: " + m,
  }
}

// Mapping type d'erreur -> code de sortie
fn to_exit(e:AppErr) -> i32 {
  match e {
    AppErr::Usage(_) => return 2,
    AppErr::Io(_)    => return 3,
    AppErr::Ffi(_)   => return 4,
    _                => return 1,
  }
}

fn load_cfg(path:str) -> Result<str, AppErr> {
  if !fs::exists(path) { return Result::Err(err_io("absent: " + path)) }
  match fs::read_to_string(path) {
    Result::Ok(t) => return Result::Ok(t),
    Result::Err(e) => return Result::Err(err_io(e)),  // on ré-étiquette I/O
  }
}

fn run() -> Result<(), AppErr> {
  let a = std.cli::args()
  if str::len(a) != 2 { return Result::Err(err_usage("app <fichier>")) }
  let txt = load_cfg(a[1])?
  io::println(txt)
  return Result::Ok(())
}

fn main()->i32 {
  match run() {
    Result::Ok(())  => return 0,
    Result::Err(e)  => { io::eprintln(to_msg(e)); return to_exit(e) }
  }
}

6.10 FFI : convertir et relayer proprement

extern "C" { fn foo_do(p:*const char) -> i32 } // 0 = OK, <0 = erreur
import std.{c}

fn foo_call(s:str) -> Result<(), AppErr> {
  let cs = c::CString::from_str(s)?           // si nul interne: Err(...) auto
  let rc = unsafe { foo_do(cs.as_ptr()) }
  if rc < 0 { return Result::Err(err_ffi("foo_do rc=" + rc.to_string())) }
  return Result::Ok(())
}

6.11 Tests d’erreurs (unitaires)

test "parse_port rejette 0" {
  match parse_port("0") {
    Result::Ok(_)   => assert(false),  // ne devrait pas arriver
    Result::Err(m)  => assert(m == "port hors plage (1..65535)")
  }
}

6.12 Écrire moins, expliquer plus (gabarits « prêt à copier »)

a) Lecture de fichier conviviale

fn show(path:str) -> Result<(), str> {
  if !std.fs::exists(path) {
    return Result::Err("E2001: fichier introuvable → " + path + "\nAstuce: passez un chemin absolu.")
  }
  std.io::print(std.fs::read_to_string(path)?)
  return Result::Ok(())
}

b) Chaînage d’étapes avec ?

fn pipeline(p:str) -> Result<(), str> {
  let raw = std.fs::read_to_string(p)?        // 1) I/O
  let cleaned = std.str::replace(raw, "\r\n", "\n")
  let n = std.str::to_int(cleaned)?           // 2) parse
  if n <= 0 { return Result::Err("valeur non positive") }
  std.io::println("ok:" + n.to_string())      // 3) ok
  return Result::Ok(())
}

6.13 Panic : cas limites uniquement

// Invariant interne brisé: continuer serait dangereux
fn expect_even(n:i32) -> () {
  if n % 2 != 0 { panic("invariant: pair attendu, reçu " + n.to_string()) }
}

6.14 Mini-FAQ débutant

6.15 Récapitulatif

let contenu = std.fs::read_to_string("config.txt")?

match std.fs::read_to_string("config.txt") {
  Result::Ok(txt) => std.io::println(txt),
  Result::Err(e)  => std.io::eprintln(e),
}

7) Interopérabilité C (FFI) — ultra-guide débutant (et au-delà)

7.1 Vocabulaire express

• ABI C : convention d’appel binaire partagée (même empilement, même nommage), nécessaire pour se comprendre à l’exécution.
• Opaque : on manipule un *mut void côté VITL sans connaître la structure interne (définie en C).
• Ownership : qui possède la mémoire ? Celui qui alloue doit libérer, avec le même allocateur.

7.2 Premier appel C (chaîne VITL → C)

import std.{io, c}

// Déclaration d'une fonction C : int puts(const char*);
extern "C" { fn puts(msg:*const char) -> i32 }

fn main() -> i32 {
  let cs = c::CString::from_str("Hello C!\n")?   // valide, pas de '\0' interne
  unsafe { _ = puts(cs.as_ptr()) }               // appel dans `unsafe`
  return 0
}

7.3 Chaînes C → VITL (qui libère ?)

De nombreuses libs C renvoient un char* allocé par elles. La règle est : on copie côté VITL, puis on libère avec free() (ou une fonction dédiée).

// C (entête côté .h)
// char* make_msg();           // alloue (malloc)
// void  free_msg(char* p);    // libère

extern "C" {
  fn make_msg() -> *mut char
  fn free_msg(p:*mut char) -> void
}

fn get_message() -> Result<String, str> {
  let p = unsafe { make_msg() }
  if p == std.ptr::null_mut() { return Result::Err("ffi: make_msg a renvoyé NULL") }

  // Copier le contenu C->VITL puis libérer côté C
  let s = std.c::copy_cstring_into_string(p)?   // <= utilitaire (copie jusqu'au '\0')
  unsafe { free_msg(p) }
  return Result::Ok(s)
}

Variante : si la lib documente « utilisez free() standard », exposez extern "C" { fn free(p:*mut void) -> void } et appelez-la, pas un delete maison.

7.4 Buffers binaires (pointeur + longueur)

Motif courant : passer un bloc mémoire à C et recevoir des octets en sortie.

// C
// int sha256(const uint8_t* data, size_t len, uint8_t* out32); // 0=OK

extern "C" { fn sha256(data:*const u8, len:usize, out:*mut u8) -> i32 }

fn hash256(input:[u8]) -> Result<[u8;32], str> {
  let mut out:[u8;32] = [0; 32]
  let rc = unsafe { sha256(input.as_ptr(), input.len(), out.as_mut_ptr()) }
  if rc != 0 { return Result::Err("ffi: sha256 rc=" + rc.to_string()) }
  return Result::Ok(out)
}

7.5 Handles opaques (pattern recommandé)

Exposez une poignée opaque et des fonctions d’usine/destruction côté C, puis encapsulez en VITL.

// C (shim)
// typedef struct Foo Foo;
// Foo* foo_create(int cap); void foo_destroy(Foo*);
// int   foo_push(Foo*, const char*); int foo_len(const Foo*);

extern "C" {
  fn foo_create(cap:i32)   -> *mut void
  fn foo_destroy(h:*mut void) -> void
  fn foo_push(h:*mut void, s:*const char) -> i32
  fn foo_len(h:*const void) -> i32
}

struct Foo { handle:*mut void }

impl Foo {
  fn new(cap:i32) -> Result<Foo,str> {
    let h = unsafe { foo_create(cap) }
    if h == std.ptr::null_mut() { return Result::Err("ffi: create failed") }
    return Result::Ok(Foo{ handle:h })
  }
  fn push(&mut self, s:str) -> Result<(),str> {
    let cs = std.c::CString::from_str(s)?
    let rc = unsafe { foo_push(self.handle, cs.as_ptr()) }
    if rc != 0 { return Result::Err("ffi: push rc=" + rc.to_string()) }
    return Result::Ok(())
  }
  fn len(&self) -> i32 { return unsafe { foo_len(self.handle) } }
  fn close(&mut self) -> () {
    if self.handle != std.ptr::null_mut() {
      unsafe { foo_destroy(self.handle) }
      self.handle = std.ptr::null_mut()
    }
  }
}

Discipline : un seul endroit « unsafe » par méthode, vérifications avant/après (NULL, codes).

7.6 Ownership & allocation — 3 règles d’or

1. Celui qui alloue libère (avec la même famille d’allocateurs).
2. Copiez de C vers VITL si vous voulez conserver la donnée après l’appel.
3. Pas de pointeur C vers une donnée VITL temporaire (durée de vie insuffisante).

7.7 Cartographier les erreurs C → Result

fn c_ok(rc:i32) -> Result<(), str> {
  if rc == 0 { return Result::Ok(()) }
  return Result::Err("ffi: rc=" + rc.to_string())
}

7.8 Liens & édition (build)

Nom des bibliothèques : libfoo.so (Linux), libfoo.dylib (macOS), foo.dll (Windows).

# Linux/macOS (bibliothèque partagée)
vitl build -O2 -L libs -lfoo -o build/app src/main.vitl

# rpath (trouver la lib au runtime)
vitl build ... -Wl,-rpath,$ORIGIN/../libs

# Statique (si libfoo.a disponible)
vitl build -O3 -L libs -Wl,-Bstatic -lfoo -Wl,-Bdynamic -o build/app src/main.vitl

# Windows (MinGW, exemple)
vitl build -O2 -L libs -lfoo -o build/app.exe src/main.vitl

7.9 En-têtes C « propres »

// foo.h
#pragma once
#include <stddef.h>   // size_t
#include <stdint.h>   // int32_t, uint8_t

#ifdef __cplusplus
extern "C" {
#endif

typedef struct Foo Foo;
Foo*  foo_create(int32_t cap);
void  foo_destroy(Foo*);
int32_t foo_push(Foo*, const char* s);     // s: NUL-terminée, UTF-8
int32_t foo_len(const Foo*);

#ifdef __cplusplus
}
#endif

Note : documentez « qui libère quoi » et la null-termination des chaînes.

7.10 Callbacks & user_data

Beaucoup d’APIs C vous rappellent via une fonction. Passez un identifiant opaque et rassemblez la logique côté C si possible.

// C
// typedef void (*on_item_fn)(const char* s, void* user);
// int enumerate(on_item_fn cb, void* user);

extern "C" { fn enumerate(cb:*const void, user:*mut void) -> i32 }

// Côté VITL, préférez écrire un petit shim C si vous devez capturer de l'état.
// Sinon, passez un identifiant (index) et rangez l'état dans une table VITL.

7.11 Tests d’intégration FFI

• Test « happy path » (rc=0), test d’échec (rc<0).
• Fuite mémoire : bouclez des create/destroy, surveillez la conso.
• Longueurs/limites : buffers exacts, off-by-one, NULL.

7.12 Mini-FAQ débutant

7.13 Mémo final

extern "C" { fn puts(msg:*const char) -> i32 }
let cstr = std.c::CString::from_str("Hello C!\n")?
unsafe { _ = puts(cstr.as_ptr()) }

8) Stdlib — ultra-guide débutant (et utile aux pros)

8.1 std.io — Entrées/sorties console

But : écrire sur la sortie standard (utilisateur) et la sortie d’erreur (diagnostics).

import std.io

io::print("Hello ")          // sans saut de ligne
io::println("world")         // avec saut de ligne
io::eprintln("attention!")   // sur STDERR

• Quand utiliser STDERR ? Pour les messages d’erreur/diagnostic afin de ne pas « polluer » la sortie normale (utile en pipelines).
• Astuce débutant : préférez println pour avoir automatiquement le retour à la ligne.

8.2 std.fs — Fichiers et chemins

But : lire/écrire des fichiers texte ou binaires, tester l’existence.

import std.{fs, io}

// Lire tout un fichier en chaîne (UTF-8)
let txt = fs::read_to_string("input.txt")?   // <= `?` propage l'erreur I/O
io::println("lu=" + txt)

// Écrire une chaîne (écrase si existe)
_ = fs::write_string("out.txt", "ok\n")?

// Lire binaire
let bytes = fs::read("image.bin")?
io::println("taille=" + bytes.len().to_string())

// Vérifier l'existence avant d'ouvrir
if !fs::exists("config.toml") {
  io::eprintln("absent: config.toml")
  // retourner un code 3 (I/O) dans `main` si approprié
}

8.3 std.str — Chaînes et utilitaires

But : opérations usuelles sur les chaînes de caractères (UTF-8).

import std.{str, io}

let s = "a b c"
io::println(str::len(s).to_string())         // 5
let parts = str::split(s, ' ')               // ["a","b","c"]
let i = str::find("abc", "b")                // 1
let out = str::replace("a_b", "_", "-")      // "a-b"

// Parsing vers nombres (renvoie Result)
let n = str::to_int("42")?     // i64
let f = str::to_float("2.5")?  // f64

• Rappel concat : convertissez les nombres → "n=" + n.to_string().
• Robustesse : mettez ? sur to_int/to_float (entrée utilisateur imprévisible).

8.4 std.math — Maths

import std.{math, io}

let d = math::sqrt(3.0*3.0 + 4.0*4.0) // 5.0
let a = math::abs(-12)                 // 12
io::println(d.to_string())

8.5 std.time — Horloge & mesure

But : mesurer un temps d’exécution, estampiller un événement.

import std.{time, io}

let t0 = time::now()
heavy_work()
io::println("ms=" + (time::now() - t0).to_string())

• Astuce : encapsulez la mesure dans une petite fonction réutilisable (voir « patrons » plus bas).

8.6 std.cli — Arguments et variables d’environnement

import std.{cli, io, str}

let argv = cli::args()
if str::len(argv) < 2 {
  io::eprintln("usage: app <fichier>")
  // return 2 dans `main` (erreur d'usage)
}

// Variables d'environnement
match cli::env("HOME") {
  Some(h) => io::println(h),
  None    => io::eprintln("HOME non défini"),
}

8.7 std.vec — Vecteurs dynamiques

But : gérer des tableaux extensibles de valeurs.

import std.{vec, io}

let mut v:[i32] = vec::with_capacity(16)
v.push(1); v.push(2); v.push(3)
for x in &v { io::println(x.to_string()) }   // itération par référence (pas de copie)

match v.pop() {
  Some(last) => io::println("last=" + last.to_string()),
  None       => {}
}
io::println("len=" + v.len().to_string())

8.8 std.debug — Assertions & debug

import std::debug

debug::assert(2 + 2 == 4)
debug::dump("state=INIT")        // trace lisible rapide
// Selon l'environnement, on peut obtenir une backtrace si activée au build `-g`.

8.9 std.err — Erreurs structurées

But : centraliser l’information d’erreur (catégorie, message, contexte) et mapper vers des codes de sortie stables.

import std::{err, io}

fn parse_threshold(s:str) -> Result<i64, err::Error> {
  match std.str::to_int(s) {
    Result::Ok(v) => return Result::Ok(v),
    Result::Err(_) => return Result::Err(err::Error::new("parse int échoué")),
  }
}

8.10 std.c — Pont C (complément rapide)

Voir la section FFI pour le guide complet. Ici, le minimum utile.

import std::c

extern "C" { fn puts(msg:*const char) -> i32 }
let cs = c::CString::from_str("Hello C!\n")?
unsafe { _ = puts(cs.as_ptr()) }

8.11 Patrons composés (recettes prêtes à copier)

Lecture robuste avec message explicite

import std::{fs, io}

fn show_file(path:str) -> Result<(), str> {
  if !fs::exists(path) {
    io::eprintln("E2001: fichier introuvable → " + path)
    io::eprintln("Astuce: lancer depuis la racine du projet ou passer un chemin absolu.")
    return Result::Err("absent")
  }
  io::print(fs::read_to_string(path)?)
  return Result::Ok(())
}

Mesure de temps, factorisée

import std::{time, io}

fn timed(label:str, f: fn()->()) -> () {
  let t0 = time::now()
  f()
  io::println(label + ":" + (time::now()-t0).to_string() + " ms")
}

Parsing fiable d’un entier (fichier config)

import std::{fs, str, err}

fn load_threshold(path:str) -> Result<i64, err::Error> {
  let s = fs::read_to_string(path)?
  match str::to_int(str::replace(s, "\n", "")) {
    Result::Ok(v) => return Result::Ok(v),
    Result::Err(_) => return Result::Err(err::Error::new("parse int échoué")),
  }
}

8.12 FAQ débutant

8.13 Aide-mémoire (quick ref)

import std.{io, fs, str, math, time, cli, vec, debug, err, c}

io::println("Hello")
_ = fs::write_string("out.txt", "ok\n")?
let n = str::len("abc") // 3
let t0 = time::now(); heavy(); io::println((time::now()-t0).to_string()+" ms")

9) Style et bonnes pratiques — ultra-guide débutant (utile aux pros)

9.1 Structure type d’un fichier

1. module (doit refléter le chemin disque)
2. imports groupés/par ordre hiérarchique
3. constantes publiques → privées
4. types (struct/enum) puis impl
5. fonctions publiques → privées
6. tests à la fin

// src/math/geom.vitl
module math.geom
import std.{math, io}

const EPS:f64 = 1e-9

struct Vec2 { x:f64, y:f64 }

impl Vec2 {
  fn norm(&self)->f64 { return (self.x*self.x + self.y*self.y).sqrt() }
}

pub fn dist(a:Vec2, b:Vec2)->f64 { return Vec2{ x:a.x-b.x, y:a.y-b.y }.norm() }

test "distance nulle sur même point" { assert(dist(Vec2{x:0,y:0}, Vec2{x:0,y:0}) < EPS) }

9.2 Nommage (clair et constant)

• snake_case pour variables/fonctions ; CamelCase pour types.
• Noms parlants : timeout_ms, max_items, parse_config.
• Préfixez les « jetables » par _ : let _unused = ... pour signaler l’intention.

// Mieux
fn read_user_file(path:str)->Result<String,str> { ... }
// À éviter
fn ruf(p:str)->Result<String,str> { ... }

9.3 Mise en forme (formatter)

• Utilisez vitl fmt régulièrement (CI conseillée).
• Lignes courtes (≈100 colonnes), blocs aérés, imports triés.
• 1 déclaration par ligne, pas d’« one-liners » opaques.

9.4 Imports

• Groupez par familles : std.{io, fs} puis vos modules internes.
• Importez juste ce qu’il faut (limite les collisions et clarifie les usages).

import std.{io, fs}
import util.{strfmt, path}

9.5 Fonctions : petite surface, retours clairs

• Une fonction = une idée. Si vous avez « et puis », scindez.
• Types explicites aux frontières (API publiques, FFI, I/O).
• Early return pour les erreurs/conditions simples → code en « flèche droite ».

// Mauvais : imbriqué
fn load(p:str)->Result<String,str>{
  if std.fs::exists(p){
    return std.fs::read_to_string(p)
  } else {
    return Result::Err("absent")
  }
}
// Mieux : early return + message clair
fn load(p:str)->Result<String,str>{
  if !std.fs::exists(p) { return Result::Err("E2001: absent:"+p) }
  return std.fs::read_to_string(p)
}

9.6 Erreurs : conventions

• Utilisez Result<T,E> pour toute opération risquée.
• Propagez avec ? tant que le message d’origine est suffisant.
• Codes de sortie stables : 0=OK, 1=panic, 2=usage, 3=I/O, 4=FFI.

fn run(path:str)->i32 {
  match app::do_work(path) {
    Result::Ok(_)  => return 0,
    Result::Err(e) => { std.io::eprintln(e); return 3 }
  }
}

9.7 Données : immutabilité, mut avec parcimonie

• Déclarez immuable par défaut (let), introduisez mut au plus près du besoin.
• Préférez les transformations claires aux mutations cachées.

let mut acc:i64 = 0
for n in 0..=100 { acc = acc + n }

9.8 Chaînes & formatage

• Convertissez explicitement : "n=" + n.to_string().
• Centralisez les formats communs (ex. util::strfmt).

9.9 Boucles, conditions, match

• Préférez match exhaustif pour les enums (vous ne « oublierez » pas de cas).
• Limitez les break/continue multiples : c’est plus lisible.

match status {
  Status::Ok      => {},
  Status::Err(e)  => std.io::eprintln(e),
}

9.10 Tests (AAA : Arrange, Act, Assert)

• Un test = un comportement. Nommez-le comme une phrase.
• Placez les tests en bas du fichier du module testé.

test "parse: nombre valide" {
  // Arrange
  let s = "42"
  // Act
  let n = std.str::to_int(s).unwrap()
  // Assert
  assert(n == 42)
}

9.11 Commentaires & documentation

• Commentez le « pourquoi », pas le « quoi » (le code dit déjà le quoi).
• Utilisez /// pour la doc générée par vitl doc.

/// Convertit une chaîne en entier signé.
/// Retourne Err si la chaîne n'est pas un entier valide.
fn parse_i64(s:str)->Result<i64,str> { return std.str::to_int(s) }

9.12 Logs & debug

• Logguez sur eprintln les diagnostics (niveau simple).
• Évitez le bruit : messages courts avec un identifiant stable (ex. E2001).

9.13 Performance (sans prématurité)

• Mesurez avant d’optimiser : std.time::now() autour du bloc.
• Évitez les copies inutiles (itération par &v).
• Allouez à l’avance si la taille est connue : vec::with_capacity.

9.14 FFI & sécurité (rappel de style)

• Encapsulez l’unsafe dans une API sûre et documentée.
• Documentez l’ownership des buffers passés au C (qui libère ?).

9.15 Exemples « avant / après »

fn r(p:str)->i32{if!std.fs::exists(p){std.io::eprintln("x");return 3}
std.io::print(std.fs::read_to_string(p).unwrap());return 0}

/// Affiche le contenu d'un fichier texte.
/// Codes : 0 ok, 3 I/O manquant.
fn run(path:str)->i32 {
  if !std.fs::exists(path) {
    std.io::eprintln("E2001: fichier introuvable → " + path)
    return 3
  }
  match std.fs::read_to_string(path) {
    Result::Ok(s)  => { std.io::print(s); return 0 },
    Result::Err(e) => { std.io::eprintln(e); return 3 },
  }
}

9.16 Checklist « revue rapide »

• [ ] Nom du module = chemin du fichier
• [ ] Imports triés et minimaux
• [ ] Fonctions courtes (≤ ~20–30 lignes) ou clairement découpées
• [ ] Types explicites aux frontières d’API
• [ ] Erreurs via Result + messages utiles (codes stables si pertinent)
• [ ] Immutabilité par défaut ; mut localisé
• [ ] Tests nommés, AAA respecté
• [ ] vitl fmt exécuté

let user_name = "Alice"
fn compute_area(w:i32, h:i32) -> i32 { return w*h }
struct Rectangle { width:i32, height:i32 }

10) Conseils par niveau — guide progressif pour tous publics

// Débutant : compteur 0..=N
module app.counter
import std.{io, cli, str}

fn main()->i32 {
  let a = cli::args()
  if str::len(a) != 2 { io::eprintln("usage: counter <n>"); return 2 }
  let n = str::to_int(a[1])?
  if n < 0 { io::eprintln("n doit être ≥ 0"); return 2 }
  for i in 0..=(n as i32) { io::println(i.to_string()) }
  return 0
}

// Intermédiaire : "cat++" avec erreurs contextualisées
module app.catpp
import std.{io, fs, cli, str, time}

fn main()->i32 {
  let a = cli::args()
  if str::len(a) < 2 { io::eprintln("usage: catpp <fichiers...>"); return 2 }
  let t0 = time::now()
  let mut shown:i32 = 0
  for i in 1..str::len(a) {
    let p = a[i]
    if !fs::exists(p) { io::eprintln("E2001: introuvable → " + p); continue }
    match fs::read_to_string(p) {
      Result::Ok(s)  => { io::print(s); shown = shown + 1 },
      Result::Err(e) => io::eprintln("E2002: lecture échouée → " + p + " (" + e + ")"),
    }
  }
  io::eprintln("ms=" + (time::now()-t0).to_string())
  return if shown > 0 { 0 } else { 3 }
}

// Pro : FFI encap + mapping d'erreurs
module app.ffi_safe
import std.{io, c}

extern "C" { fn puts(msg:*const char)->i32 }

fn c_puts_line(s:str)->Result<(),str> {
  let cs = c::CString::from_str(s)?
  let rc = unsafe { puts(cs.as_ptr()) }
  if rc < 0 { return Result::Err("E0701: puts a échoué") }
  return Result::Ok(())
}

fn main()->i32 {
  match c_puts_line("Hello C!\n") {
    Result::Ok(_)  => return 0,
    Result::Err(e) => { io::eprintln(e); return 4 }
  }
}

11) Limites (version Light) — version détaillée, tout public

11.1 Pas de threads natifs

Vitte Light n’inclut pas de modèle de threads intégré. Cela signifie qu’un même processus VITL n’exécutera pas deux fonctions « en parallèle » sur plusieurs cœurs. En pratique, la plupart des petits outils n’en ont pas besoin : lecture/écriture de fichiers, transformation de texte, génération de rapports ou appels systèmes séquentiels restent instantanés à l’échelle humaine. L’absence de threads évite aussi une grande classe de bugs (verrous oubliés, interblocages, conditions de course) et simplifie énormément le débogage.

Si vous devez paralléliser des traitements lourds (par exemple, compresser un grand nombre de fichiers, calculer des hachages, convertir des images), la stratégie recommandée consiste à lancer plusieurs processus du même binaire et à distribuer le travail entre eux. C’est simple à raisonner : chaque processus a sa propre mémoire, ne partage rien, et l’OS se charge d’exploiter tous les cœurs. Vous pouvez coordonner ces processus via des fichiers temporaires, des pipes, des numéros de tâches, ou un petit superviseur en VITL qui répartit des chemins d’entrée sur N sous-processus. Pour les cas encore plus spécifiques (réseau, GPU, planification fine), appuyez-vous sur une bibliothèque native via FFI C qui expose la parallélisation en interne, tout en gardant une interface VITL minimaliste et sûre.

11.2 Pas de GC complet (usage de Rc/Weak)

Vitte Light ne s’appuie pas sur un ramasse-miettes global. La mémoire est gérée par références comptées (Rc<T>) : lorsqu’il n’existe plus de référence « forte » vers une donnée, elle est libérée immédiatement. C’est facile à comprendre, déboguer et anticiper. La seule vigilance concerne les cycles forts (A pointe vers B et B vers A en « fort ») qui ne peuvent pas se libérer tout seuls. La parade est simple : pour les liens de « retour » (parent → enfant → parent), utilisez une Weak sur un des côtés. Vous évitez ainsi la fuite de mémoire sans devoir installer un GC.

Concrètement, structurez vos données avec un propriétaire clair (l’élément qui vit plus longtemps) et des observateurs qui n’empêchent pas la libération. Par exemple, un « Document » peut posséder en Rc ses « Sections », tandis que chaque « Section » ne conserve qu’un Weak vers son « Document ». Au moment de la suppression, tout se libère de manière déterministe. Si vous manipulez des graphes complexes, faites un petit audit visuel : repérez les boucles A ↔ B et convertissez le lien de retour en Weak. Pour des structures gigantesques et dynamiques où un GC serait utile, déléguez la structure au C (ou à une lib avec GC intégré) derrière un wrapper VITL finement documenté sur l’ownership.

11.3 Génériques partiels

Le système de types couvre les cas fréquents (fonctions et structures paramétrées simples), mais n’offre pas tous les raffinements des langages dédiés à la méta-programmation lourde. En clair : on privilégie des signatures explicites et des conversions claires aux « types magiques ». Pour un outil de 50-300 lignes, c’est un avantage : vous lisez l’API en un coup d’œil et vous évitez les erreurs implicites.

Quand vous sentez que vous forcez le langage (cascade de paramètres de type, abstractions très profondes), c’est souvent un signal pour revenir à des types concrets et des fonctions dédiées aux 2-3 cas qui comptent, ou pour mettre la généricité « exotique » derrière une API C minuscule. Vous gardez une interface VITL stable et vous laissez la sophistication au moteur natif.

11.4 FFI limité à l’ABI C

L’interopérabilité de Vitte Light vise l’ABI C. Cela garantit un pont fiable et portable avec un très vaste écosystème (libc, zlib, SQLite, etc.). En revanche, pour des bibliothèques C++/Rust/Go, vous devrez fournir un shim C : une petite couche qui expose des fonctions C pures (paramètres scalaires, pointeurs, longueurs), et qui s’occupe en interne d’appeler le code C++/Rust/Go. C’est une pratique standard : elle clarifie les responsabilités, stabilise la surface d’échange et simplifie le débogage.

Le contrat à respecter est simple : les chaînes passées au C doivent être des CString valides (UTF-8 sans \0 interne) et leur durée de vie doit couvrir l’appel. Documentez clairement qui alloue et qui libère chaque tampon. Si la lib vous renvoie un pointeur alloué de son côté, prévoyez la fonction de libération correspondante et appelez-la systématiquement. En cas d’erreur, mappez les codes natifs vers des messages clairs côté VITL et convertissez en codes de sortie stables (par exemple, « 4 » pour une erreur FFI).

11.5 Performances et mémoire : à quoi s’attendre

Pour des scripts et utilitaires, Vitte Light offre des temps de démarrage très courts et des binaires légers, avec des performances « assez bonnes » en I/O et en calcul numérique classique. L’absence de threads intégrés ne pénalise pas les tâches séquentielles, et l’absence de GC évite des pauses non déterministes. Les optimisations usuelles suffisent le plus souvent : lire/écrire en blocs plutôt que caractère par caractère, éviter les copies inutiles, réutiliser des tampons, convertir explicitement pour éviter les promotions coûteuses, et compiler en -O2 (ou -O3 si le binaire final le justifie). Si un hot-spot reste déterminant, déportez-le dans une fonction C spécialisée et appelez-la via FFI.

11.6 I/O intensives et très gros fichiers

Pour des fichiers énormes (journaux massifs, dumps), privilégiez le traitement en flux : lire par blocs (ou ligne par ligne) et traiter au fil de l’eau. Évitez de charger tout un fichier en mémoire, sauf si c’est réellement nécessaire. Cette approche garde la consommation mémoire stable et rend votre utilitaire robuste face à des entrées plus volumineuses que prévu. En complément, mesurez le temps (std.time::now()) et affichez une synthèse sobre en sortie d’erreur (durée, octets lus, lignes traitées) pour diagnostiquer facilement les goulots d’étranglement.

11.7 Portabilité et environnement

Vitte Light vise Linux, BSD, macOS et Windows. Quelques différences existent selon l’OS (droits d’exécution, chemins, encodages de console). Restez sur des chemins relatifs maîtrisés, vérifiez exists avant lecture, et affichez des messages d’erreur concrets (chemin, cause). En FFI, tenez compte des conventions d’édition de liens (-L/-l, rpath) et fournissez des instructions claires pour retrouver la bibliothèque au lancement (variable d’environnement, dossier libs/ du projet).

11.8 Quand « sortir » du périmètre Vitte Light

Posez-vous trois questions simples. 1) Le besoin est-il ponctuel et localisé ? Si oui, vous pouvez souvent rester en VITL et, si nécessaire, appeler une ou deux fonctions C ciblées. 2) Le besoin est-il central et persistant (calcul distribué, UI lourde, moteur 3D, GC sophistiqué) ? Dans ce cas, mieux vaut déléguer ce cœur à une lib native éprouvée et ne garder en VITL que la « colle » et le flux. 3) Le besoin touche-t-il l’infrastructure (threads complexes, scheduling, GPU) au point d’absorber tout le projet ? Alors utilisez un langage/outil dédié pour ce sous-système et exposez une interface C propre pour que VITL puisse l’orchestrer.

11.9 En résumé

Vitte Light est un langage d’efficacité pragmatique : rapide à apprendre, rapide à livrer, fluide à maintenir. Les limites énumérées ici ne sont pas des blocages, mais des garde-fous qui vous aident à décider quand rester simple, quand composer avec des processus, et quand brancher une bibliothèque native. En gardant l’interface VITL claire et en documentant vos hypothèses (ownership, erreurs, chemins), vous obtiendrez des outils robustes, portables et faciles à diagnostiquer—exactement ce dont on a besoin au quotidien.

12) Codes de sortie — guide ultra complet, tout public

12.1 Principes de base

• Succès : retournez 0 depuis main.
• Échec : retournez un entier non nul (idéalement documenté) et écrivez un message lisible sur stderr via std.io::eprintln.
• Panic : un panic("...") interrompt le programme et se traduit par un échec (convention : 1), avec un message/trace en mode debug (-g).
• Lisibilité : combinez un code stable + un message clair pour aider humains et machines.

12.2 Table des codes (noyau + recommandations)

VITL standardise un petit noyau (0–4). Vous pouvez étendre avec des identifiants supplémentaires si votre outil le nécessite.

Bonnes pratiques : restez dans une petite plage (0–15) et documentez-la. Les environnements POSIX normalisent l’état sur 8 bits (0–255). Des valeurs négatives peuvent être interprétées de façon imprévisible — évitez-les.

12.3 Exemple canonique : mapper les erreurs vers un code

// Style recommandé : une fonction "run" retourne Result, "main" traduit en code.
module app.main
import std.{io, fs, str}

const EX_OK:i32      = 0
const EX_GENERIC:i32 = 1
const EX_USAGE:i32   = 2
const EX_IO:i32      = 3

fn run() -> Result<(), str> {
  let argv = std.cli::args()
  if str::len(argv) < 2 {
    return Result::Err("usage: app <fichier>")
  }
  let path = argv[1]
  if !std.fs::exists(path) {
    return Result::Err("E2001: fichier introuvable → " + path)
  }
  std.io::print(std.fs::read_to_string(path)?) // `?` propage l'erreur I/O
  return Result::Ok(())
}

fn main() -> i32 {
  match run() {
    Result::Ok(()) => { return EX_OK }
    Result::Err(msg) => {
      std.io::eprintln(msg)
      // Heuristique simple : décider du code en fonction du message
      if std.str::starts_with(msg, "usage:") { return EX_USAGE }
      if std.str::starts_with(msg, "E2001:") { return EX_IO }
      return EX_GENERIC
    }
  }
}

12.4 Messages d’erreur : forme et ton

• Clairs, concis (une à deux lignes). Indiquez quoi + où + piste.
• stderr pour les erreurs (eprintln), stdout pour les résultats.
• Stable : conservez les mêmes codes et formats dans le temps ; évitez de « changer de sens ».

// I/O robuste (extrait)
let path = argv[1]
if !std.fs::exists(path) {
  std.io::eprintln("E2001: fichier introuvable → " + path)
  std.io::eprintln("Astuce: lancez depuis la racine du projet ou passez un chemin absolu.")
  return EX_IO
}

12.5 Conventions CLI usuelles

• Usage invalide → code 2, afficher l’aide courte. Évitez une stacktrace.
• Échec interne (bug, invariant cassé) → code 1, suggérer -g pour plus de traces.
• Lecture/écriture → code 3, préciser le chemin et la cause probable.
• FFI → code 4, inclure le return code natif si disponible.

12.6 Intégration shell, CI/CD et pipelines

# bash
vitl build -O2 -o build/app src/main.vitl && ./build/app data.txt
echo "exit=$?"

# pipelines
set -o pipefail
./produce | ./filter | ./consume
echo "pipeline exit=$?"

12.7 JSON + codes (outil scriptable)

Pour un outil consommé par d’autres programmes, couplez un code avec une sortie JSON courte afin de mêler lisibilité humaine et robustesse machine.

// Exemple : en cas d'erreur, JSON minimal sur stdout, détails sur stderr.
fn main() ->i32 {
  match run() {
    Result::Ok(()) => { std.io::println(r#"{"ok":true}"#); return 0 }
    Result::Err(msg) => {
      std.io::eprintln(msg)
      std.io::println(r#"{"ok":false,"code":2}"#)
      return 2
    }
  }
}

12.8 Tests des codes de sortie

Vérifiez vos codes avec des tests système (scripts) et des tests VITL ciblés.

# test shell (ex.)
./app                       # manque d'arguments
test $? -eq 2 || echo "attendu EX_USAGE"

./app data/missing.txt
test $? -eq 3 || echo "attendu EX_IO"

12.9 Questions fréquentes

• Dois-je inventer 100 codes ? Non. 3–8 codes bien choisis suffisent pour 99 % des utilitaires.
• Puis-je changer un code plus tard ? Évitez. Si nécessaire, conservez l’ancien comme alias (temporaire) et annoncez la déprecation.
• Et Windows ? Restez sur de petits entiers positifs. Les shells/CI modernes les propagent correctement.

12.10 Résumé opérationnel

13) Diagnostics courants — guide ultra complet, tout public

13.1 Méthode de triage (rapide et efficace)

1. Lire le message complet (ligne, colonne, module) avant d’essayer quelque chose.
2. Isoler un MRE (Mini Repro d’Erreur) : réduisez le code au plus petit exemple qui reproduit le problème (souvent 1–2 fichiers).
3. Compiler en mode debug pour des messages plus riches : vitl build -O0 -g -o build/app src/main.vitl.
4. Inspection statique avec vitl check src/ (style, imports, incohérences communes).
5. Lire/ajouter des types aux frontières (I/O, FFI, conversions) pour faire apparaître les incompatibilités.
6. Tracer ce qui se passe : ajouter std.io::eprintln("dbg: ...") ou std.debug::dump("state=...") si dispo.
7. Documenter le correctif dans le code (commentaire court) si l’origine était subtile (encodage, chemin relatif, etc.).

13.2 Anatomie d’un message d’erreur

Un diagnostic VITL indique typiquement où (fichier:ligne:colonne), quoi (code, libellé) et piste (conseil). Exemple :

src/app/main.vitl:12:15: E0002: types incompatibles
  aide: caster avec `as` ou convertir avec `.to_string()` selon le contexte

• Code (p.ex. E0002) → catégorie (typage, I/O, FFI…)
• Libellé → nature précise (ex. « types incompatibles »)
• Aide → action concrète (cast, import, check du chemin…)

13.3 Erreurs de compilation fréquentes (avec correctifs)

E0001 — Symbole inconnu / import manquant

// Mauvais
module app.main
fn main()->i32 {
  std.io::pritnln("hi")   // faute de frappe + pas d'import
  return 0
}

// Correct
module app.main
import std.io
fn main()->i32 {
  std.io::println("hi")
  return 0
}

• Vérifier l’orthographe et l’import (et l’ordre module → imports → code).
• Nom de module = chemin du fichier. Exemple : src/util/str.vitl ⇒ module util.str.

E0002 — Types incompatibles (cast/convertir)

// Mauvais
let n:i32 = 3
let x:f64 = 0.5
let y = n + x      // i32 + f64 → erreur

// Correct (cast local)
let n:i32 = 3
let x:f64 = 0.5
let y = (n as f64) + x

// Chaînes
std.io::println("n=" + n)              // E0002
std.io::println("n=" + n.to_string())  // OK

Règle : conversion explicite pour les nombres (as), .to_string() pour concaténer avec du texte.

E0003 — Variable non initialisée

// Mauvais
let mut acc:i32
if cond { acc = 1 }
std.io::println(acc.to_string())

// Correct
let mut acc:i32 = 0
if cond { acc = 1 }
std.io::println(acc.to_string())

E0401 — match non exhaustif

enum Mode { Fast, Slow }

match m {
  Mode::Fast => do_fast(),
  // manque Slow → E0401
}

// Correct
match m {
  Mode::Fast => do_fast(),
  Mode::Slow => do_slow(),
}

E0501 — Conflit de mutabilité

Déclarez let mut si vous modifiez une variable. Évitez les écritures concurrentes dans la même expression.

E0601 — Format chaîne invalide (p.ex. CString)

Pour le FFI, une CString ne doit pas contenir \0 interne. Voir la section FFI ci-dessous.

13.4 Erreurs d’exécution fréquentes (runtime)

E2001 — Fichier introuvable (I/O)

let path = "data/config.txt"
if !std.fs::exists(path) {
  std.io::eprintln("E2001: fichier introuvable → " + path)
  return 3 // EX_IO
}
let txt = std.fs::read_to_string(path)?  // `?` propage l'erreur I/O

• Lancez depuis la racine du projet ou utilisez un chemin absolu.
• CI/CD : vérifiez que le fichier est copié dans l’arborescence d’exécution.

E0301 — Dépassement d’index

let v:[i32] = [1,2,3]
let x = v[3]  // panique: hors bornes
// Correct
if i < v.len() { let x = v[i] }

E0201 — Division par zéro

fn div(a:i32, b:i32) -> Result<i32,str> {
  if b == 0 { return Result::Err("division par zéro") }
  return Result::Ok(a / b)
}

E0801 — UTF-8 invalide

En lecture texte, fichiers mal encodés ⇒ préférer lecture binaire + conversion contrôlée ou nettoyer l’entrée.

13.5 FFI (C) — erreurs typiques et correctifs

E1001 — Appel FFI hors unsafe

// Mauvais
extern "C" { fn puts(msg:*const char)->i32 }
fn main()->i32 {
  let s = std.c::CString::from_str("Hi\n")
  puts(s.unwrap().as_ptr()) // E1001
  return 0
}

// Correct
extern "C" { fn puts(msg:*const char)->i32 }
fn main()->i32 {
  let s = std.c::CString::from_str("Hi\n")?
  unsafe { _ = puts(s.as_ptr()) }
  return 0
}

E0601 — CString invalide (caractère nul)

let msg = std.c::CString::from_str("ok\0oops") // E0601
if msg.is_err() { return Result::Err("E0601: CString invalide (\\0 interne)") }

E0701 — FFI: code de retour d’échec

let rc = unsafe { foo_call(...) }
if rc != 0 {
  std.io::eprintln("E0701: FFI call failed (rc="+rc.to_string()+")")
  return 4 // EX_FFI
}

13.6 Quand « rien » ne marche : stratégie pas-à-pas

1. Confirmez l’environnement (répertoire courant, OS, droits d’accès).
2. Affichez les arguments au démarrage (std.cli::args()) pour vérifier ce que reçoit votre programme.
3. Utilisez des chemins absolus pour les ressources (temporairement, pour lever le doute).
4. Ajoutez des logs ciblés (une ligne par étape importante, sur stderr si possible).
5. Réduisez à un MRE et remontez progressivement jusqu’à l’état initial.

13.7 Performance ou bug ? (petits tests rapides)

let t0 = std.time::now()
heavy()
std.io::eprintln("dbg: heavy ms=" + (std.time::now()-t0).to_string())

• Si le temps explose, suspectez une copie inutile, une lecture répétée de fichier, ou une boucle mal bornée.
• Pré-allouez avec std.vec::with_capacity si la taille est connue.

13.8 Gabarits de messages (prêts à coller)

13.9 Par thèmes : checklists de résolution

13.10 Tests de non-régression (verrouiller le fix)

test "lecture fichier: path manquant renvoie EX_IO" {
  // pseudo-test: isolez la fonction qui résout un code depuis un message
  let rc = map_error_to_exit("E2001: fichier introuvable → data.txt")
  assert(rc == 3)
}

13.11 Exemples « messages enrichis »

// I/O robuste
let path = argv[1]
if !std.fs::exists(path) {
  std.io::eprintln("E2001: fichier introuvable → " + path)
  std.io::eprintln("Astuce: lancer depuis la racine du projet ou passer un chemin absolu.")
  return 3
}

// FFI robuste
let msg = std.c::CString::from_str("ok\n")
if msg.is_err() { return Result::Err("E0601: CString invalide (caractère nul)") }
unsafe { _ = puts(msg.unwrap().as_ptr()) }

13.12 Mini-FAQ diagnostics

• Dois-je tout convertir en String ? Non. Convertissez au moment d’afficher/concaténer. Gardez des types numériques pour calculer.
• Pourquoi un fichier introuvable en CI mais pas en local ? Chemin relatif et répertoire courant différents. Utilisez des chemins absolus ou synchronisez les dossiers dans votre pipeline.
• Je n’ai pas de trace lors d’un échec. Recompilez avec -g et assurez-vous que l’échec est bien un panic ou qu’un message est émis sur stderr.

Résumé — Lisez le message complet · isolez un MRE · vitl check + -O0 -g · ajoutez des types aux frontières · messages enrichis et codes stables · verrouillez le fix par un test.

14) Checklist avant de livrer

14.1 Contrôle express (60 s)

• [ ] Le programme se lance par vitl run et le binaire par ./build/app sans surprise.
• [ ] vitl fmt et vitl check ne signalent rien.
• [ ] vitl test passe localement.
• [ ] Codes de sortie documentés et respectés (0/1/2/3/4).
• [ ] README/usage minimal à jour.

14.2 Structure & modules

• [ ] Dossiers séparés : /src (VITL), /libs (C/FFI), /build (artefacts), /tests (si besoin).
• [ ] Un fichier = un module. Nom de module = chemin disque (ex. src/util/str.vitl → module util.str).
• [ ] Fichiers d’entrée main.vitl ou app/main.vitl clairement identifiés.
• [ ] Imports triés par hiérarchie, sans doublons ni imports morts.

14.3 Build & artefacts

• [ ] Débogage : vitl build -O0 -g -o build/app src/main.vitl OK.
• [ ] Release : vitl build -O3 -o build/app src/main.vitl OK (ou -O2 selon politique).
• [ ] Artefacts attendus présents (build/app, docs, éventuel .vitbc).
• [ ] (Optionnel) --emit-ir / --emit-bytecode génèrent des sorties exploitables.

14.4 Qualité du code & style

• [ ] vitl fmt appliqué à src/ et tests/.
• [ ] vitl check sans avertissement bloquant (imports morts, types flous, variables inutilisées).
• [ ] Noms explicites (snake_case pour variables/fonctions, CamelCase pour types).
• [ ] Types explicites aux frontières (I/O, FFI, API publique).

14.5 Gestion des erreurs & UX

• [ ] API système → Result<T,E> + propagation ? ; pas de panic() hors cas irrécupérables.
• [ ] Codes de sortie stables : 0 succès · 1 panic/générique · 2 usage CLI · 3 I/O · 4 FFI.
• [ ] Messages « enrichis » sur stderr (conseil d’usage, chemin, cause).
• [ ] --help clair si CLI : usage, options, exemples, codes de sortie.

14.6 Entrées/Sorties & fichiers

• [ ] Chemins relatifs vs absolus maîtrisés ; si ressources, test de présence via std.fs::exists.
• [ ] Lecture texte → UTF-8 attendu (si doute, lecture binaire + conversion contrôlée).
• [ ] Écritures atomiques si nécessaire (temp + rename) pour éviter la corruption.
• [ ] Gestion des grosses tailles (streaming au lieu de tout en mémoire, si pertinent).

14.7 Mémoire & sécurité

• [ ] Usage de Rc/Weak compris ; pas de cycles forts non désirés.
• [ ] Pas d’unsafe hors FFI ; pas de pointeur C stocké vers une String temporaire.
• [ ] Accès indexés protégés (limites vérifiées, get() si nécessaire).

14.8 FFI (C) — si utilisé

• [ ] Déclarations extern "C" correctes (types stables : int32_t, size_t…).
• [ ] Appels C dans unsafe { ... } uniquement.
• [ ] Chaînes : std.c::CString::from_str (sans \0 interne), durée de vie respectée.
• [ ] Ownership documenté (qui alloue/libère, et comment).
• [ ] Codes de retour C testés : non-zéro ⇒ message + sortie 4.
• [ ] Lien/bibliothèques : -L, -l, rpath et variantes (statique/dynamique) validés.

14.9 Tests & couverture

• [ ] vitl test passe en local et en CI.
• [ ] Au moins un test d’erreur (usage CLI, fichier manquant, FFI erreur).
• [ ] Un test rapide « fumée » (smoke) qui lance le binaire avec un cas trivial.

14.10 Performance & ressources

• [ ] Chemins chauds sans copies inutiles (ex. vec::with_capacity si taille connue).
• [ ] Mesure simple (std.time::now()) ajoutée/validée pour opérations lourdes, retirée ou passée en mode --verbose.

14.11 Documentation & exemples

• [ ] Sections de doc /// pour les fonctions publiques (but, paramètres, erreurs, exemple minimal).
• [ ] vitl doc génère une sortie propre (si configuré).
• [ ] README : comment exécuter, compiler, tester, codes de sortie, exemple « copier-coller ».
• [ ] CHANGELOG/notes de version (si applicable).

14.12 Packaging & distribution

• [ ] Binaire release reproduisible (mêmes options), nommage clair (app-<os>-<arch> si multiplateforme).
• [ ] Licence incluse si redistribution.
• [ ] (Optionnel) Somme de contrôle (SHA256) et signature.
• [ ] Archive propre (pas de fichiers temporaires ni artefacts de debug).

14.13 CI/CD

• [ ] Pipeline : fmt → check → build (debug) → test → build (release) → (doc) → package → publier artefacts.
• [ ] Variables d’environnement et chemins validés (exécution depuis la racine repo).
• [ ] Tests rapides pour ne pas bloquer les PRs (stratégie « rapide par défaut » + jobs lourds en nightly si besoin).

14.14 Observabilité & journalisation

• [ ] Logs d’erreur sur stderr, messages concis, pas de secrets en clair.
• [ ] Niveau de verbosité contrôlable (-v/--verbose), silencieux par défaut.

14.15 Post-livraison (dernier mètre)

• [ ] Smoke test exécuté sur l’artefact final (même archive que l’utilisateur).
• [ ] Plan de rollback si blocant.
• [ ] Ticket(s) ou notes de suivi ouverts pour dettes techniques restantes.

# Formatage, lint, build, tests (local)
vitl fmt src/ tests/
vitl check src/
vitl build -O0 -g -o build/app src/main.vitl
vitl test
vitl build -O3 -o build/app src/main.vitl

# Exécution simple
./build/app --help
./build/app <args>

FIN DU GUIDE