cc-libs/PLAN.md

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:

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:

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:

########
#      #
#      #
#      #
#      #
#      #
#      #
########

Pseudo-rendu plein:

########
########
########
########

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:

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:

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.