<?php
namespace nur\b\io;

use nur\b\ICloseable;

/**
 * Class IReader: abstraction d'une source à partir de laquelle on peut lire
 * (fichier, flux, etc.)
 */
interface IReader extends ICloseable {
  /** si ce reader est basé sur une resource, la retourner, sinon null. */
  function getResource();

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

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

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

  /**
   * lire la prochaine ligne. la ligne est retournée *sans* le caractère de fin
   * de ligne [\r]\n
   *
   * @throws EOFException si plus aucune ligne n'est disponible
   * @throws IOException si une erreur se produit
   */
  function readLine(): string;

  /** lire toutes les lignes du fichier */
  function readLines(): array;

  /**
   * lire tout le contenu en une seule fois, puis, si $close==true, fermer le
   * fichier
   *
   * @throws IOException si une erreur se produit
   */
  function getContents(bool $close=true): string;

  function unserialize(?array $options=null, bool $close=true);

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