/*********************************************************************************************************************
 *
 *   ██████╗ ███╗   ███╗██████╗ ██╗     ██╗███╗   ██╗███████╗
 *  ██╔════╝ ████╗ ████║██╔══██╗██║     ██║████╗  ██║██╔════╝
 *  ██║      ██╔████╔██║██║  ██║██║     ██║██╔██╗ ██║█████╗
 *  ██║      ██║╚██╔╝██║██║  ██║██║     ██║██║╚██╗██║██╔══╝
 *  ╚██████╗ ██║ ╚═╝ ██║██████╔╝███████╗██║██║ ╚████║███████╗
 *   ╚═════╝ ╚═╝     ╚═╝╚═════╝ ╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝
 *
 *  CmdLine — Documentation d'utilisation
 *  Version v23 — Surcharges print(const char*) / println(const char*)
 *  Fichiers : CmdLine.h  /  CmdLine.cpp  /  CmdLineKey.h
 *
 *  Auteur   : Biechy Jean-Marc — Ecole d'Informatique Institution Saint-Jean Colmar France 2026
 *
 *********************************************************************************************************************/

/*====================================================================================================================
 *  NOUVEAUTÉ v23 — SURCHARGES print(const char*) / println(const char*)
 *====================================================================================================================
 *
 *  PROBLÈME OBSERVÉ
 *  ─────────────────
 *  Lors de l'affichage d'une adresse MAC formatée avec sprintf() :
 *
 *    char hexByte[3];
 *    sprintf(hexByte, "%02X", conf_TMP.mac[i]);   // ex : "A3"
 *    cmdLine.print(hexByte);                       // ← appel concerné
 *
 *  Sans surcharge explicite print(const char*), le compilateur C++ résout
 *  cet appel via le template générique :
 *
 *    template<typename T>
 *    void print(T a) { _stream.print(a); ... }    // T = char* (ou char[3])
 *
 *  Ce chemin fonctionnait dans la plupart des cas, mais :
 *    1. Le choix du compilateur n'est pas garanti en présence des autres
 *       surcharges (const char*, __FlashStringHelper*, String...).
 *    2. En ESP32, avec la lib WiFi + BluetoothSerial, des ambiguïtés de
 *       résolution ont pu conduire à un comportement imprévue.
 *    3. L'absence de surcharge explicite rendait ce cas non documenté.
 *
 *  CRASH OBSERVÉ (contexte ESP32)
 *  ────────────────────────────────
 *  Guru Meditation Error: Core 1 panic'ed (StoreProhibited)
 *  EXCCAUSE: 0x1d  EXCVADDR: 0x00000000
 *
 *  EXCVADDR = 0x00000000 → déréférencement d'un pointeur null.
 *  Contexte : affichage de l'adresse MAC via sprintf + cmdLine.print(hexByte)
 *  lors de l'exécution d'une commande réseau (status / info).
 *
 *  CORRECTION v23
 *  ───────────────
 *  Ajout de deux surcharges explicites dans CmdLine.h (déclaration)
 *  et CmdLine.cpp (implémentation) :
 *
 *    void print  (const char *str);   // chaîne C RAM → 3 canaux
 *    void println(const char *str);   // chaîne C RAM + \r\n → 3 canaux
 *
 *  Ces surcharges suivent exactement le même patron que les autres :
 *    Canal 1 : _stream.print(str)              → Serial / SerialBT
 *    Canal 2 : _c->print(str)   si connecté    → Telnet / WiFi
 *    Canal 3 : _btStream->print(str) si activé → Bluetooth (v22+)
 *
 *  CODE CORRIGÉ (dans le sketch .ino)
 *  ────────────────────────────────────
 *  // AVANT — pouvait causer une ambiguïté ou crash selon contexte :
 *  char hexByte[3];
 *  sprintf(hexByte, "%02X", conf_TMP.mac[i]);
 *  cmdLine.print(hexByte);         // résolution par template T=char*
 *
 *  // APRÈS — surcharge explicite garantie :
 *  char hexByte[3];
 *  sprintf(hexByte, "%02X", conf_TMP.mac[i]);   // formate en hex majuscule avec zéro
 *  cmdLine.print(hexByte);                       // surcharge const char* → toujours valide
 *
 *  Les deux lignes sont identiques dans le sketch. La correction est dans la lib.
 *
 *====================================================================================================================
 *  FICHIERS DE LA LIBRAIRIE
 *====================================================================================================================
 *
 *  CmdLineKey.h     Sélection de plateforme, inclusion librairie réseau,
 *                   codes touches (KEY_xxx), machine d'état TelnetState,
 *                   constantes IAC Telnet.
 *                   → INCLUS AUTOMATIQUEMENT par CmdLine.h
 *
 *  CmdLine.h        Classe CmdLine, constantes paramétrables (#define),
 *                   structure CanalState, déclarations publiques/privées.
 *
 *  CmdLine.cpp      Implémentation complète de toutes les méthodes.
 *
 *====================================================================================================================
 *  PLATEFORMES SUPPORTÉES
 *====================================================================================================================
 *
 *  Plateforme               Connexion réseau    Librairie requise
 *  ──────────────────────   ─────────────────   ────────────────────────────
 *  Arduino UNO R4 Minima    Telnet TCP           Ethernet@2.0.2
 *  + Shield Ethernet W5500  port 23
 *
 *  ESP8266                  Telnet TCP           ESP8266WiFi (core incluse)
 *                           port 23
 *
 *  ESP32                    Telnet TCP           WiFi (core incluse)
 *                           port 23
 *
 *  ESP32                    Bluetooth Serial     BluetoothSerial (core incluse)
 *                           (pas de port TCP)
 *
 *====================================================================================================================
 *  ARCHITECTURE 3 CANAUX (inchangée depuis v22)
 *====================================================================================================================
 *
 *  cmdLine.print("texte") — ou — cmdLine.print(hexByte) — ou — cmdLine.print(42)
 *       │
 *       ├──► _stream.print()    → Canal 1 : Serial / SerialBT
 *       ├──► _c->print()        → Canal 2 : Telnet TCP (si client connecté)
 *       └──► _btStream->print() → Canal 3 : Bluetooth SerialBT (si activé v22)
 *
 *====================================================================================================================
 *  TABLEAU DES SURCHARGES print / println (v23 complet)
 *====================================================================================================================
 *
 *  Surcharge                           Définie dans   Depuis
 *  ──────────────────────────────────  ─────────────  ──────
 *  println()                           .cpp           v16
 *  print(const char *str)              .cpp           v23  ← NOUVEAU
 *  println(const char *str)            .cpp           v23  ← NOUVEAU
 *  print(const __FlashStringHelper*)   .cpp           v16
 *  println(const __FlashStringHelper*) .cpp           v16
 *  print<T>(T a)          [template]   .h             v16
 *  println<T>(T a)        [template]   .h             v16
 *  print(long, int base)               .cpp           v21
 *  println(long, int base)             .cpp           v21
 *  print(unsigned long, int base)      .cpp           v21
 *  println(unsigned long, int base)    .cpp           v21
 *  write(const uint8_t*, size_t)       .cpp           v21
 *
 *  Règle de résolution du compilateur C++ (du plus prioritaire au moins) :
 *    1. Surcharge exacte non-template → const char*, F(), long+base...
 *    2. Template générique T          → String, int, float, bool...
 *  Avant v23 : char* tombait dans le template (2). Depuis v23 : surcharge exacte (1).
 *
 *====================================================================================================================
 *  HISTORIQUE DES VERSIONS
 *====================================================================================================================
 *
 *  v23  Ajout surcharges explicites print(const char*) / println(const char*).
 *       Cas d'usage : formatage hexadécimal sprintf(buf, "%02X", val) + print(buf).
 *       Avant v23 : T=char* passait par le template, ce qui fonctionnait mais
 *       sans garantie de résolution en présence des autres surcharges.
 *       Crash ESP32 observé (StoreProhibited, EXCVADDR=0x0) dans ce contexte.
 *       FIX v23 : déclaration dans CmdLine.h + implémentation dans CmdLine.cpp.
 *       Architecture BT 3 canaux inchangée. Aucune autre modification.
 *
 *  v22  CORRECTION BUG retour Bluetooth absent — 3 passes successives.
 *       Passe 1 : Serial hardcodé → _stream (print/println/write dans .cpp et templates .h).
 *       Passe 2 : ajout 3ème canal _btStream (Stream*) + setBluetoothOutput().
 *       Passe 3 : BluetoothSerial* → Stream* (conflit symboles WiFi/BT résolu).
 *
 *  v21  Ajout print(long, int base) / println(long, int base) / write(buf, len).
 *       Compatible Serial.print(val, DEC/HEX/OCT/BIN).
 *
 *  v20  Multi-plateforme : UNO R4, ESP8266, ESP32 WiFi, ESP32 Bluetooth.
 *       Fichier CmdLineKey.h séparé. Renommage CmdLineTelnet_UNOR4 → CmdLine.
 *       updateTelnet() → updateNetwork(). _clientConnected() abstrait.
 *
 *  v19  Correction bug casse — cmdStrcmpLower() / cmdStrncmpLower().
 *
 *  v18  setEcho(bool) / getEcho(). CMDLINE_ECHO_DEFAULT. HISTORY_SIZE renommé.
 *
 *  v17  Documentation complète. CMDLINE_CASE_INSENSITIVE.
 *
 *  v16  Réécriture basée sur Terminal.cpp (rweather, MIT).
 *       Machine d'état Telnet 9 états. Timeout ESC 40ms. Backspace "\b \b".
 *
 *====================================================================================================================
 *  FICHIERS MODIFIÉS EN v23
 *====================================================================================================================
 *
 *  CmdLine.h
 *    - En-tête : version v23
 *    - Historique : entrée v23 ajoutée
 *    - Section publique : déclarations print(const char*) / println(const char*)
 *    - Commentaire bloc surcharges : liste mise à jour (char* mentionné)
 *
 *  CmdLine.cpp
 *    - En-tête : version v23
 *    - Organisation : section 19 mentionnée v22/v23
 *    - Section 19 commentaire : liste des surcharges mise à jour + explication char*
 *    - Nouvelles fonctions : print(const char*) / println(const char*) — 3 canaux
 *
 *  CmdLineKey.h
 *    - En-tête : version v23
 *    (aucune modification fonctionnelle)
 *
 *====================================================================================================================
 *  USAGE — EXEMPLE COMPLET ESP32 WiFi + Bluetooth (identique v22)
 *====================================================================================================================
 *
 *  // ── Dans le sketch .ino ──────────────────────────────────────────────────────
 *
 *  #define CMDLINE_PLATFORM_ESP32
 *  #include <CmdLine.h>
 *  #include "BluetoothSerial.h"
 *
 *  BluetoothSerial SerialBT;
 *
 *  CmdLine       cmdLine(Serial);
 *  CmdLineServer serverTelnet(23);
 *  CmdLineClient clientTelnet;
 *
 *  void cmdStatus(const char *arg) {
 *      // Affichage adresse MAC — v23 : surcharge char* explicite
 *      uint8_t mac[6] = { 0x08, 0x3A, 0xF2, 0xB9, 0x1F, 0xC4 };
 *      for (int i = 0; i < 6; i++) {
 *          char hexByte[3];
 *          sprintf(hexByte, "%02X", mac[i]);    // formate en hex majuscule avec zéro
 *          cmdLine.print(hexByte);              // surcharge const char* → Serial+Telnet+BT
 *          if (i < 5) cmdLine.print(F(":"));
 *      }
 *      cmdLine.println();
 *  }
 *
 *  void setup() {
 *      Serial.begin(115200);
 *      SerialBT.begin("ESP32-CmdLine");
 *      cmdLine.setBluetoothOutput(&SerialBT);
 *      WiFi.begin(ssid, password);
 *      serverTelnet.begin();
 *      cmdLine.begin(commands, countof(commands));
 *  }
 *
 *  void loop() {
 *      cmdLine.update();
 *      if (serverTelnet.hasClient()) clientTelnet = serverTelnet.available();
 *      cmdLine.updateNetwork(clientTelnet);
 *  }
 *
 *********************************************************************************************************************/
