<?php
namespace nur\b\io;

/**
 * Interface IWriter: abstraction d'une destination dans laquelle on peut écrire
 * (fichier, flux, etc.)
 */
interface IWriter {
  ## gestion de l'indentation

  /** réinitialiser l'indentation */
  function resetIndent(?int $indentLevel=0, ?string $indentString=null): void;

  /** augmenter le niveau d'indentation et retourner le niveau précédent */
  function indent(): int;

  /** diminuer le niveau d'indentation */
  function dedent(): void;

  ## écriture sur le flux

  /** si ce writer est basé sur une resource, la retourner, sinon null. */
  function getResource();

  /** vérifier si ce writer écrit sur un terminal */
  function isatty(): bool;

  /** si ce writer est basé sur une resource, ajouter un filtre. */
  function appendFilter(string $filterName, ?int $readWrite=null, $params=null): void;

  /** si ce writer est basé sur une resource, ajouter un filtre. */
  function prependFilter(string $filterName, ?int $readWrite=null, $params=null): void;

  /** si ce writer est basé sur une resource, spécifier l'encoding. */
  function setEncodingFilter(string $to, string $from="utf-8"): void;

  /**
   * obtenir la chaine qui serait affichée avec l'une des fonctions write() ou
   * print()
   */
  function toString(string $sep, array $values, bool $updateIndent=true): string;

  /**
   * écrire une suite de valeurs collées les unes aux autres dans la destination
   */
  function write(...$values): IWriter;

  /**
   * afficher une suite de valeurs collées les unes aux autres suivie d'un saut
   * à la ligne
   */
  function wnl(...$values): IWriter;

  /**
   * écrire une suite de valeurs séparées par des espaces dans la destination.
   * les valeurs null et false sont ignorées (comme inexistantes)
   */
  function print(...$values): IWriter;

  /**
   * afficher une suite de valeurs séparées par des espaces suivie d'un saut à
   * la ligne. les valeurs null et false sont ignorées (comme inexistantes)
   */
  function pnl(...$values): IWriter;

  /** afficher les lignes */
  function writeLines(iterable $lines): IWriter;

  /** fermer le fichier si c'est nécessaire */
  function close(bool $close=true): void;
}
