<?php
namespace nur\data\expr;

/**
 * Interface IContext: un contexte à partir duquel sont accédées certaines
 * données
 */
interface IContext {
  /** schéma d'une représentation d'un contexte sous forme de tableau */
  const SCHEMA = [
    "sources" => [null, null, "sources des données de ce contexte", true],
    "exprs" => [null, null, "liste des expressions définies dans ce contexte", true],
    "conds" => [null, null, "liste des expressions conditionnelles définies dans ce contexte", true],
  ];
  /** schéma d'une description de source sous forme de tableau */
  const SOURCE_SCHEMA = [
    "name" => [null, null, "identifiant de la source de donnée", true],
    "title" => [null, null, "description de la source de donnée, pour affichage", false],
  ];
  /** schéma d'une description d'une expression sous forme de tableau */
  const EXPR_SCHEMA = IExpr::SCHEMA;
  /** schéma d'une description d'une condition sous forme de tableau */
  const COND_SCHEMA = IExpr::SCHEMA;

  /**
   * @return array des informations sur ce contexte, sous la forme d'un tableau
   * conforme au schéma {@link IContext::SCHEMA}
   */
  function getContextInfos(): array;

  /** @return mixed obtenir la valeur correspondant au chemin */
  function getValue(string $pkey);

  /** @return mixed obtenir la valeur de la session correspondant au chemin */
  function getSession(string $pkey);

  /** @return mixed obtenir la valeur de configuration correspondant au chemin */
  function getConfig(string $pkey);

  /**
   * appeler la méthode spécifiée et retourner le résultat de l'appel.
   *
   * La méthode peut être dans un des formats suivants:
   * - "Class::method" ou ["Class", "method"] pour appeler une méthode statique
   * de la classe spécifiée
   * - "::method", ["method"] ou [null, "method"] pour appeler une méthode
   * statique de la classe par défaut
   * - "->method", ["->method"] ou [anything, "->method"] pour appeler une
   * méthode de l'objet par défaut
   *
   * La classe et l'objet par défaut sont déterminés par le contexte.
   *
   * Si $method est un tableau, il peut contenir des éléments supplémentaires
   * qui sont considérés comme des arguments de l'appel, e.g:
   *     $context->callMethod(["MyClass", "method", "hello", "world"]);
   * est équivant à:
   *     MyClass::method("hello", "world");
   */
  function callMethod($method);
}