<?php
namespace nur\sery\output;

/**
 * Interface IMessenger: un objet pouvant afficher des messages de l'application
 */
interface IMessenger {
  const DEBUG = 0, MINOR = 1, NORMAL = 2, MAJOR = 3, NONE = 4;
  const MIN_LEVEL = self::DEBUG, MAX_LEVEL = self::MAJOR;

  /** réinitialiser les paramètres de l'objet */
  function resetParams(?array $params=null): void;

  /**
   * créer une copie de cet objet avec éventuellement des paramètres différents
   */
  function clone(?array $params=null): self;

  /**
   * commencer une section.
   *
   * flush tous les messages en cours. ne peut être imbriqué. on peut considérer
   * que c'est une sorte de "reset" de l'objet
   */
  function section($content, ?callable $func=null, ?int $level=null): void;

  /**
   * commencer un chapitre.
   *
   * peut être imbriqué dans un autre chapitre. terminer automatiquement
   * l'action en cours avec un résultat neutre
   */
  function title($content, ?callable $func=null, ?int $level=null): void;

  /** ajouter une description au chapitre courant. */
  function desc($content, ?int $level=null): void;

  /**
   * comencer une action dans le chapitre courant.
   *
   * peut être imbriqué dans une autre action.
   */
  function action($content, ?callable $func=null, ?int $level=null): void;

  /**
   * ajouter une étape à l'action courante.
   *
   * démarrer une action le cas échéant (et la terminer aussitôt)
   */
  function step($content, ?int $level=null): void;

  /**
   * terminer l'action courante avec le résultat "succès"
   *
   * démarrer une action le cas échéant (et la terminer aussitôt)
   */
  function asuccess($content=null, ?int $overrideLevel=null): void;

  /**
   * terminer l'action courante avec le résultat "échec"
   *
   * démarrer une action le cas échéant (et la terminer aussitôt)
   */
  function afailure($content=null, ?int $overrideLevel=null): void;

  /**
   * terminer l'action courante avec le résultat "neutre"
   *
   * démarrer une action le cas échéant (et la terminer aussitôt)
   */
  function adone($content=null, ?int $overrideLevel=null): void;

  /**
   * terminer l'action courante avec le résultat "succès", "échec" ou "neutre"
   * en fonction de la valeur de $result
   * - si c'est un booléen, true vaut succès, false vaut échec
   * - si c'est une exception, c'est un échec et le message est affiché
   * - sinon, le résultat est neutre et le message est affiché s'il n'est pas null
   *
   * démarrer une action le cas échéant (et la terminer aussitôt)
   */
  function aresult($result=null, ?int $overrideLevel=null): void;

  /** afficher une donnée non structurée */
  function print($content, ?int $level=null): void;

  /** afficher un événément "information" */
  function info($content, ?int $level=null): void;

  /** afficher un événément "information importante" */
  function note($content, ?int $level=null): void;

  /** afficher un événément "avertissement" */
  function warning($content, ?int $level=null): void;

  /** afficher un événément "erreur" */
  function error($content, ?int $level=null): void;

  /**
   * terminer le chapitre en cours. toutes les actions en cours sont terminées
   * avec un résultat neutre.
   *
   * @param bool $all faut-il terminer *tous* les chapitres ainsi que la section
   * en cours?
   */
  function end(bool $all=false): void;
}
