<?php
namespace nur\sery\os\proc;

/**
 * Interface ICmd: une abstraction d'une ou plusieurs commandes à lancer
 */
interface ICmd {
  /**
   * vérifier si cette commande a besoin que son entrée standard soit connectée
   * à un flux.
   */
  function isNeedsStdin(): bool;

  /**
   * vérifier si cette commande a besoin que sa sortie standard soit connectée
   * à un terminal
   */
  function isNeedsTty(): bool;

  /**
   * Ajouter le préfixe spécifié à la dernière commande de la liste
   *
   * si $prefix est un array, quoter puis assembler les éléments du tableau.
   * sinon ce doit être une chaine de caractère et elle est prise telle quelle
   */
  function addPrefix($prefix): void;

  /**
   * Ajouter des redirections à la dernière commande de la liste
   *
   * $redir spécifie le type de redirection demandée:
   * - "default" | null: $output reçoit STDOUT et STDERR n'est pas redirigé
   * - "outonly" | "noerr": $output ne reçoit que STDOUT et STDERR est perdu
   * - "erronly" | "noout": $output ne reçoit que STDERR et STDOUT est perdu
   * - "both" | "err2out": $output reçoit STDOUT et STDERR
   * - sinon c'est une redirection spécifique, et la valeur est rajoutée telle
   * quelle à la ligne de commande ($output est ignoré)
   *
   * $output est le nom d'un fichier qui reçoit les redirections, ou null pour
   * la valeur par défaut. spécifier $append==true pour ajouter au fichier
   * $output au lieu de l'écraser
   */
  function addRedir(?string $redir, $output=null, bool $append=false, $input=null): void;

  /** Obtenir le texte de la commande comme elle serait saisie dans un shell */
  function getCmd(?string $sep=null): string;

  /**
   * Lancer la commande avec passthru() et retourner le code de retour dans la
   * variable $retcode
   *
   * voici la différence entre passthru(), system() et exec()
   * +----------------+-----------------+----------------+----------------+
   * |    Command     | Displays Output | Can Get Output | Gets Exit Code |
   * +----------------+-----------------+----------------+----------------+
   * | passthru()     | Yes (raw)       | No             | Yes            |
   * | system()       | Yes (as text)   | Last line only | Yes            |
   * | exec()         | No              | Yes (array)    | Yes            |
   * +----------------+-----------------+----------------+----------------+
   *
   * @return bool true si la commande s'est lancée sans erreur, false sinon
   */
  function passthru(int &$retcode=null): bool;

  /**
   * Comme {@link passthru()} mais lancer la commande spécifiée avec system().
   * Cf la doc de {@link passthru()} pour les autres détails
   */
  function system(string &$output=null, int &$retcode=null): bool;

  /**
   * Comme {@link passthru()} mais lancer la commande spécifiée avec exec().
   * Cf la doc de {@link passthru()} pour les autres détails
   */
  function exec(array &$output=null, int &$retcode=null): bool;

  /**
   * Lancer la commande dans un processus fils via un shell et attendre la fin
   * de son exécution
   */
  function fork_exec(int &$retcode=null): bool;
}
