docs: remove carre plan
This commit is contained in:
parent
217b0e4e83
commit
9cc86a18e6
177
PLAN.md
177
PLAN.md
@ -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 <n>`: taille du carre, par defaut `8`
|
||||
- `-x <n>`: colonne de depart, par defaut centree si possible
|
||||
- `-y <n>`: ligne de depart, par defaut centree si possible
|
||||
- `-char <c>`: 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 <n>`: dessine plusieurs carres, utile avec `-random`, par defaut `1`
|
||||
- `-delay <s>`: 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.
|
||||
Loading…
Reference in New Issue
Block a user