From 9cc86a18e644ede1483679f72a29c309aed73d9f Mon Sep 17 00:00:00 2001 From: Guillaume ARM Date: Wed, 10 Jun 2026 20:08:51 +0200 Subject: [PATCH] docs: remove carre plan --- PLAN.md | 177 -------------------------------------------------------- 1 file changed, 177 deletions(-) delete mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index a98da75..0000000 --- a/PLAN.md +++ /dev/null @@ -1,177 +0,0 @@ -# Programme `carre` Plan - -## Objectif - -Ajouter un nouveau programme ComputerCraft nommé `carre` qui dessine des carres dans le terminal. - -Le programme doit etre utile pour un test simple, mais assez amusant pour explorer plusieurs rendus: carre fixe, carre plein, carre aleatoire, et repetition de carres. - -Le code doit aussi pouvoir servir d'exemple pedagogique pour debutants Lua. L'implementation pourra donc contenir quelques commentaires en francais, courts et utiles, pour expliquer les etapes importantes sans noyer le programme. - -## Emplacement - -- Programme: `programs/carre.lua` -- Tests: `tests/programs/carre_test.lua` ou `tests/carre_test.lua`, selon les conventions existantes au moment de l'implementation -- Package: nouveau package separe `trapos-sandbox`, afin de tester `ccpm` sans inclure `carre` directement dans `trapos` - -## Interface Proposee - -Commande de base: - -```text -carre [options] -``` - -Options: - -- `-size `: taille du carre, par defaut `8` -- `-x `: colonne de depart, par defaut centree si possible -- `-y `: ligne de depart, par defaut centree si possible -- `-char `: caractere utilise pour dessiner, par defaut `#` -- `-fill`: dessine un carre plein au lieu d'un contour -- `-random`: choisit une taille, une position et un caractere aleatoires simples compatibles avec le terminal -- `-count `: dessine plusieurs carres, utile avec `-random`, par defaut `1` -- `-delay `: pause entre deux carres quand `-count` est superieur a `1`, par defaut `0` -- `-clear`: efface l'ecran avant de dessiner -- `-help` / `--help`: affiche l'aide -- `-version` / `--version`: affiche la version du package via `/apis/libversion` - -Exemples: - -```text -carre -carre -size 12 -char * -clear -carre -size 6 -fill -x 4 -y 3 -carre -random -carre -random -count 5 -delay 0.2 -clear -``` - -## Comportement Attendu - -- Le programme dessine dans le terminal courant avec `term.setCursorPos()` et `write()`. -- Si `-clear` est donne, il appelle `term.clear()` avant le dessin. -- Sans `-x` ou `-y`, le carre est centre dans la zone disponible quand la taille du terminal le permet. -- Les coordonnees et tailles sont bornees pour eviter les erreurs ou les dessins hors ecran. -- `-size 1` dessine un seul caractere. -- `-size 2` dessine un carre minimal valide. -- Si `-fill` est absent, seul le contour est dessine. -- Si `-fill` est present, toute la surface est remplie. -- Si `-random` est present, les options explicites doivent rester prioritaires quand c'est raisonnable: par exemple `carre -random -char @` garde `@` mais randomise taille/position. -- Si `-count` est superieur a `1`, chaque carre est dessine successivement sur le meme ecran par defaut. Avec `-clear`, l'ecran est efface avant chaque carre pour produire une petite animation. -- Les couleurs ne sont pas prioritaires pour la premiere version: l'objectif est de garder un programme lisible pour debutants. - -## Regles De Validation Des Arguments - -- `-size` doit etre un entier positif. -- `-x` et `-y` doivent etre des entiers positifs. -- `-count` doit etre un entier positif. -- `-delay` doit etre un nombre positif ou nul. -- `-char` prend le premier caractere non vide fourni. -- Option inconnue: afficher une erreur courte puis suggerer `carre -help`. -- Argument invalide: afficher une erreur courte puis quitter sans stack trace. - -## Idee D'Implementation - -Structure minimale dans `programs/carre.lua`: - -1. Charger `/apis/libversion` pour `--version`. -2. Definir `printUsage()`. -3. Parser `...` avec une boucle simple sur `args`. -4. Recuperer `term.getSize()`. -5. Calculer une configuration finale de dessin. -6. Dessiner avec une fonction locale `drawSquare(x, y, size, char, fill)`. -7. Repeter selon `count`, avec `sleep(delay)` si necessaire. - -Commentaires a privilegier dans le code: - -- Expliquer pourquoi on lit `...` pour recuperer les arguments du programme. -- Expliquer le calcul de centrage. -- Expliquer la difference entre contour et remplissage. -- Expliquer que le mode aleatoire borne les valeurs pour rester visible dans le terminal. - -Commentaires a eviter: - -- Commentaires qui repetent exactement le code, par exemple `-- ajoute 1 a x`. -- Gros blocs de theorie Lua qui rendraient le programme moins lisible. - -Pseudo-rendu contour: - -```text -######## -# # -# # -# # -# # -# # -# # -######## -``` - -Pseudo-rendu plein: - -```text -######## -######## -######## -######## -``` - -## Tests Proposes - -Ajouter des tests CraftOS-PC avec `/apis/libtest.lua` pour les parties deterministes: - -- Parse des options de base. -- Rejet des valeurs invalides. -- Calcul de centrage avec une taille de terminal simulee. -- Calcul de bornage quand le carre depasse la zone disponible. -- Rendu contour dans une surface terminal simulee. -- Rendu plein dans une surface terminal simulee. -- Mode random teste avec une source aleatoire injectable ou avec des invariants seulement: taille positive, position visible, pas d'erreur. - -Pour rendre le programme testable sans gros refactor, l'implementation peut garder les fonctions pures dans le fichier et n'executer `main(...)` qu'a la fin. Si les conventions du depot preferent tester seulement les programmes via execution CraftOS-PC, adapter les tests en consequence. - -## Verification - -Apres implementation: - -```text -just check -just trapos-exec 'shell.run("/programs/carre", "-size", "5", "-clear")' -just trapos-exec 'shell.run("/programs/carre", "-random", "-count", "3", "-delay", "0")' -``` - -Si des tests sont ajoutes: - -```text -just trapos-exec 'shell.run("/programs/runtest", "/tests/carre_test.lua")' -``` - -## Packaging - -- Creer le nouveau package `packages/trapos-sandbox/ccpm.json`. -- Ne pas ajouter `carre` au package principal `trapos`. -- Ajouter `programs/carre.lua` dans les fichiers du package `trapos-sandbox`. -- Bumper la version du package `trapos-sandbox` quand le comportement change. -- Reporter la meme version dans `packages/index.json`. -- Verifier que `carre --version` retourne bien la version attendue. - -## Decisions Validees - -- `carre` doit etre dans un nouveau package separe, pas dans `trapos`, pour faciliter les tests de `ccpm`. -- Le package s'appelle `trapos-sandbox`. -- Le programme s'appelle `carre.lua`, sans accent. -- Les commentaires en francais sont souhaites pour rendre le code utile a des debutants. -- Les couleurs sont repoussees: le programme doit rester simple et pedagogique pour la premiere version. - -## Questions Restantes - -- `carre -random -count N` doit-il garder tous les carres visibles par defaut, ou faut-il finalement effacer entre chaque dessin meme sans `-clear`? - -## Hors Scope Pour La Premiere Version - -- Dessin de rectangles non carres. -- Animation avancee avec rebonds. -- Interface interactive au clavier. -- Sauvegarde du dessin dans un fichier. -- Support multi-caracteres pour les bordures. -- Couleurs de texte ou de fond.