<?php
namespace nur\sery\output;

/**
 * Interface IMessenger: un objet pouvant afficher des messages de l'application
 */
interface IMessenger {
  const LEVEL_DEBUG = -1, LEVEL_NORMAL = 0, LEVEL_MAJOR = 1;

  /**
   * 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, ?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, ?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, ?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 success($content=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 failure($content=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 neutral($content=null): void;

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

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

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

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

  /** ajouter 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);
}
