From 2964153e54b269c833810194f16bd9bccc9267ce Mon Sep 17 00:00:00 2001
From: Jephte Clain <Jephte.Clain@univ-reunion.fr>
Date: Sun, 31 Dec 2023 22:37:04 +0400
Subject: [PATCH] modifs.mineures sans commentaires

---
 .idea/nulib.iml                               |   2 +-
 composer.json                                 |   2 +-
 php/src_php/ICloseable.php                    |  10 ++
 php/{src_sys => src_php}/README.md            |   2 +-
 php/{src_sys => src_php/content}/IContent.php |   2 +-
 .../content}/IPrintable.php                   |   2 +-
 .../content}/IStaticContent.php               |   2 +-
 php/{src_sys => src_php/content}/content.php  |   3 +-
 php/{src_sys => src_php}/func.php             |   2 +-
 php/src_php/iter/AbstractIterator.php         | 148 ++++++++++++++++++
 php/src_php/json/JsonException.php            |  20 +++
 php/src_ref/{sys => php}/ref_func.php         |   2 +-
 .../{sys => php/content}/contentTest.php      |   5 +-
 .../{sys => php/content}/impl/AContent.php    |   4 +-
 .../{sys => php/content}/impl/APrintable.php  |   4 +-
 .../content}/impl/AStaticContent.php          |   5 +-
 php/tests/{sys => php/content}/impl/ATag.php  |   6 +-
 php/tests/{sys => php/content}/impl/html.php  |   4 +-
 php/tests/{sys => php}/funcTest.php           |   2 +-
 19 files changed, 205 insertions(+), 22 deletions(-)
 create mode 100644 php/src_php/ICloseable.php
 rename php/{src_sys => src_php}/README.md (78%)
 rename php/{src_sys => src_php/content}/IContent.php (89%)
 rename php/{src_sys => src_php/content}/IPrintable.php (85%)
 rename php/{src_sys => src_php/content}/IStaticContent.php (87%)
 rename php/{src_sys => src_php/content}/content.php (99%)
 rename php/{src_sys => src_php}/func.php (99%)
 create mode 100644 php/src_php/iter/AbstractIterator.php
 create mode 100644 php/src_php/json/JsonException.php
 rename php/src_ref/{sys => php}/ref_func.php (96%)
 rename php/tests/{sys => php/content}/contentTest.php (92%)
 rename php/tests/{sys => php/content}/impl/AContent.php (65%)
 rename php/tests/{sys => php/content}/impl/APrintable.php (62%)
 rename php/tests/{sys => php/content}/impl/AStaticContent.php (59%)
 rename php/tests/{sys => php/content}/impl/ATag.php (77%)
 rename php/tests/{sys => php/content}/impl/html.php (86%)
 rename php/tests/{sys => php}/funcTest.php (99%)

diff --git a/.idea/nulib.iml b/.idea/nulib.iml
index 4a9634a..670e1a9 100644
--- a/.idea/nulib.iml
+++ b/.idea/nulib.iml
@@ -7,7 +7,7 @@
       <sourceFolder url="file://$MODULE_DIR$/php/src_output" isTestSource="false" packagePrefix="nulib\output\" />
       <sourceFolder url="file://$MODULE_DIR$/php/src_web" isTestSource="false" packagePrefix="nulib\web\" />
       <sourceFolder url="file://$MODULE_DIR$/php/src_ref" isTestSource="false" packagePrefix="nulib\ref\" />
-      <sourceFolder url="file://$MODULE_DIR$/php/src_sys" isTestSource="false" packagePrefix="nulib\sys\" />
+      <sourceFolder url="file://$MODULE_DIR$/php/src_php" isTestSource="false" packagePrefix="nulib\php\" />
       <excludeFolder url="file://$MODULE_DIR$/vendor" />
     </content>
     <orderEntry type="inheritedJdk" />
diff --git a/composer.json b/composer.json
index e4c7711..544d425 100644
--- a/composer.json
+++ b/composer.json
@@ -19,7 +19,7 @@
 		"psr-4": {
 			"nulib\\": "php/src_base",
 			"nulib\\ref\\": "php/src_ref",
-			"nulib\\sys\\": "php/src_sys",
+			"nulib\\php\\": "php/src_php",
 			"nulib\\output\\": "php/src_output",
 			"nulib\\web\\": "php/src_web"
 		}
diff --git a/php/src_php/ICloseable.php b/php/src_php/ICloseable.php
new file mode 100644
index 0000000..7b26316
--- /dev/null
+++ b/php/src_php/ICloseable.php
@@ -0,0 +1,10 @@
+<?php
+namespace nulib\php;
+
+/**
+ * Interface ICloseable: un objet que l'on peut fermer
+ */
+interface ICloseable {
+  /** fermer l'objet et libérer les resources */
+  function close(): void;
+}
diff --git a/php/src_sys/README.md b/php/src_php/README.md
similarity index 78%
rename from php/src_sys/README.md
rename to php/src_php/README.md
index 08ccfe2..65ec6ba 100644
--- a/php/src_sys/README.md
+++ b/php/src_php/README.md
@@ -1,4 +1,4 @@
-# nulib\sys
+# nulib\php
 
 Ce package contient des services généraux spécifiques à PHP
 
diff --git a/php/src_sys/IContent.php b/php/src_php/content/IContent.php
similarity index 89%
rename from php/src_sys/IContent.php
rename to php/src_php/content/IContent.php
index dfcfd86..4d2de30 100644
--- a/php/src_sys/IContent.php
+++ b/php/src_php/content/IContent.php
@@ -1,5 +1,5 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php\content;
 
 /**
  * Interface IContent: un objet capable de produire du contenu à afficher. le
diff --git a/php/src_sys/IPrintable.php b/php/src_php/content/IPrintable.php
similarity index 85%
rename from php/src_sys/IPrintable.php
rename to php/src_php/content/IPrintable.php
index e1b20c2..b17fae1 100644
--- a/php/src_sys/IPrintable.php
+++ b/php/src_php/content/IPrintable.php
@@ -1,5 +1,5 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php\content;
 
 /**
  * Interface IPrintable: un objet qui écrit du contenu sur la sortie standard
diff --git a/php/src_sys/IStaticContent.php b/php/src_php/content/IStaticContent.php
similarity index 87%
rename from php/src_sys/IStaticContent.php
rename to php/src_php/content/IStaticContent.php
index 5d2a10b..7d1eec9 100644
--- a/php/src_sys/IStaticContent.php
+++ b/php/src_php/content/IStaticContent.php
@@ -1,5 +1,5 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php\content;
 
 /**
  * Interface IStaticContent: comme {@link IContent} mais la liste retournée est
diff --git a/php/src_sys/content.php b/php/src_php/content/content.php
similarity index 99%
rename from php/src_sys/content.php
rename to php/src_php/content/content.php
index da86aad..6114c8c 100644
--- a/php/src_sys/content.php
+++ b/php/src_php/content/content.php
@@ -1,7 +1,8 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php\content;
 
 use nulib\cl;
+use nulib\php\func;
 
 /**
  * Class content: gestionnaire de contenu (statique ou dynamique)
diff --git a/php/src_sys/func.php b/php/src_php/func.php
similarity index 99%
rename from php/src_sys/func.php
rename to php/src_php/func.php
index cf7f381..2747273 100644
--- a/php/src_sys/func.php
+++ b/php/src_php/func.php
@@ -1,5 +1,5 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php;
 
 use Closure;
 use nulib\cl;
diff --git a/php/src_php/iter/AbstractIterator.php b/php/src_php/iter/AbstractIterator.php
new file mode 100644
index 0000000..01ecac3
--- /dev/null
+++ b/php/src_php/iter/AbstractIterator.php
@@ -0,0 +1,148 @@
+<?php
+namespace nulib\php\iter;
+
+use Exception;
+use Iterator;
+use nulib\os\EOFException;
+use nulib\php\ICloseable;
+
+/**
+ * Class AbstractIterator: implémentation de base d'un itérateur
+ */
+abstract class AbstractIterator implements Iterator, ICloseable {
+  /**
+   * initialiser les ressources nécessaires à l'itération.
+   *
+   * les exceptions lancées par cette méthode sont ignorées.
+   */
+  protected function _setup(): void {}
+
+  /**
+   * lancer un traitement avant de commencer l'itération.
+   *
+   * cette méthode est appelée après {@link _setup()} et l'objet est garanti
+   * d'être dans un état valide.
+   *
+   * cette méthode est prévue pour être surchargée par l'utilisateur, mais il
+   * doit gérer lui-même les exceptions éventuelles.
+   */
+  protected function beforeIter() {}
+
+  /**
+   * retourner le prochain élément. lancer l'exception {@link EOFException} pour
+   * indiquer que plus aucun élément n'est disponible
+   *
+   * le cas échéant, initialiser $key
+   *
+   * @throws EOFException
+   */
+  abstract protected function _next(&$key);
+
+  /**
+   * modifier l'élement retourné par {@link _next()} avant de le retourner.
+   *
+   *
+   * cette méthode est prévue pour être surchargée par l'utilisateur, mais il
+   * doit gérer lui-même les exceptions éventuelles.
+   */
+  protected function cook(&$item) {}
+
+  /**
+   * lancer un traitement avant de terminer l'itération et de libérer les
+   * resources
+   *
+   * cette méthode est appelée avant {@link _teardown()} et l'objet est garanti
+   * d'être dans un état valide.
+   *
+   * cette méthode est prévue pour être surchargée par l'utilisateur, mais il
+   * doit gérer lui-même les exceptions éventuelles.
+   */
+  protected function beforeClose(): void {}
+
+  /**
+   * libérer les ressources allouées.
+   *
+   * les exceptions lancées par cette méthode sont ignorées.
+   */
+  protected function _teardown(): void {}
+
+  function close(): void {
+    $this->rewind();
+  }
+
+  #############################################################################
+  # Implémentation par défaut
+
+  private $setup = false;
+  private $valid = false;
+  private $toredown = true;
+
+  private $index = 0;
+  protected $key;
+  protected $item = null;
+
+  function key() {
+    return $this->key;
+  }
+
+  function current() {
+    return $this->item;
+  }
+
+  function next(): void {
+    if ($this->toredown) return;
+    $this->valid = false;
+    try {
+      $item = $this->_next($key);
+    } catch (EOFException $e) {
+      $this->beforeClose();
+      try {
+        $this->_teardown();
+      } catch (Exception $e) {
+      }
+      $this->toredown = true;
+      return;
+    }
+    $this->cook($item);
+    $this->item = $item;
+    if ($key !== null) {
+      $this->key = $key;
+    } else {
+      $this->index++;
+      $this->key = $this->index;
+    }
+    $this->valid = true;
+  }
+
+  function rewind(): void {
+    if ($this->setup) {
+      if (!$this->toredown) {
+        $this->beforeClose();
+        try {
+          $this->_teardown();
+        } catch (Exception $e) {
+        }
+      }
+      $this->setup = false;
+      $this->valid = false;
+      $this->toredown = true;
+      $this->index = 0;
+      $this->key = null;
+      $this->item = null;
+    }
+  }
+
+  function valid(): bool {
+    if (!$this->setup) {
+      try {
+        $this->_setup();
+      } catch (Exception $e) {
+      }
+      $this->setup = true;
+      $this->toredown = false;
+      $this->beforeIter();
+      $this->next();
+    }
+    return $this->valid;
+  }
+}
diff --git a/php/src_php/json/JsonException.php b/php/src_php/json/JsonException.php
new file mode 100644
index 0000000..97c3d8c
--- /dev/null
+++ b/php/src_php/json/JsonException.php
@@ -0,0 +1,20 @@
+<?php
+namespace nulib\php\json;
+
+use RuntimeException;
+
+class JsonException extends RuntimeException {
+  static final function json_last_error(?string $prefix=null): ?self {
+    $json_last_error = json_last_error();
+    if ($json_last_error === JSON_ERROR_NONE) return null;
+    $message = json_last_error_msg()." ($json_last_error)";
+    if ($prefix) $message = "$prefix: $message";
+    return new static($message);
+  }
+
+  static final function ensure_json_value($value, ?string $prefix=null) {
+    $exception = self::json_last_error($prefix);
+    if ($exception === null) return $value;
+    else throw $exception;
+  }
+}
diff --git a/php/src_ref/sys/ref_func.php b/php/src_ref/php/ref_func.php
similarity index 96%
rename from php/src_ref/sys/ref_func.php
rename to php/src_ref/php/ref_func.php
index 12523f8..451c81b 100644
--- a/php/src_ref/sys/ref_func.php
+++ b/php/src_ref/php/ref_func.php
@@ -1,5 +1,5 @@
 <?php
-namespace nulib\ref\sys;
+namespace nulib\ref\php;
 
 class ref_func {
   const CALL_ALL_PARAMS_SCHEMA = [
diff --git a/php/tests/sys/contentTest.php b/php/tests/php/content/contentTest.php
similarity index 92%
rename from php/tests/sys/contentTest.php
rename to php/tests/php/content/contentTest.php
index 47cfe0f..3bf5ad2 100644
--- a/php/tests/sys/contentTest.php
+++ b/php/tests/php/content/contentTest.php
@@ -1,7 +1,8 @@
 <?php
-namespace nulib\sys;
+namespace nulib\php\content;
 
-use nulib\sys\impl\html;
+use nulib\php\content\content;
+use nulib\php\content\impl\html;
 use PHPUnit\Framework\TestCase;
 
 class contentTest extends TestCase {
diff --git a/php/tests/sys/impl/AContent.php b/php/tests/php/content/impl/AContent.php
similarity index 65%
rename from php/tests/sys/impl/AContent.php
rename to php/tests/php/content/impl/AContent.php
index 8d8266e..c53c376 100644
--- a/php/tests/sys/impl/AContent.php
+++ b/php/tests/php/content/impl/AContent.php
@@ -1,7 +1,7 @@
 <?php
-namespace nulib\sys\impl;
+namespace nulib\php\content\impl;
 
-use nulib\sys\IContent;
+use nulib\php\content\IContent;
 
 class AContent implements IContent {
   function getContent(): iterable {
diff --git a/php/tests/sys/impl/APrintable.php b/php/tests/php/content/impl/APrintable.php
similarity index 62%
rename from php/tests/sys/impl/APrintable.php
rename to php/tests/php/content/impl/APrintable.php
index fba0121..7a75c2f 100644
--- a/php/tests/sys/impl/APrintable.php
+++ b/php/tests/php/content/impl/APrintable.php
@@ -1,7 +1,7 @@
 <?php
-namespace nulib\sys\impl;
+namespace nulib\php\content\impl;
 
-use nulib\sys\IPrintable;
+use nulib\php\content\IPrintable;
 
 class APrintable implements IPrintable {
   function print(): void {
diff --git a/php/tests/sys/impl/AStaticContent.php b/php/tests/php/content/impl/AStaticContent.php
similarity index 59%
rename from php/tests/sys/impl/AStaticContent.php
rename to php/tests/php/content/impl/AStaticContent.php
index 4916a2b..cf81cd9 100644
--- a/php/tests/sys/impl/AStaticContent.php
+++ b/php/tests/php/content/impl/AStaticContent.php
@@ -1,7 +1,8 @@
 <?php
-namespace nulib\sys\impl;
+namespace nulib\php\content\impl;
 
-use nulib\sys\IStaticContent;
+use nulib\php\content\IStaticContent;
+use nulib\php\content\impl\html;
 
 class AStaticContent implements IStaticContent {
   function getContent(): iterable {
diff --git a/php/tests/sys/impl/ATag.php b/php/tests/php/content/impl/ATag.php
similarity index 77%
rename from php/tests/sys/impl/ATag.php
rename to php/tests/php/content/impl/ATag.php
index d01e66f..1342a7a 100644
--- a/php/tests/sys/impl/ATag.php
+++ b/php/tests/php/content/impl/ATag.php
@@ -1,8 +1,8 @@
 <?php
-namespace nulib\sys\impl;
+namespace nulib\php\content\impl;
 
-use nulib\sys\content;
-use nulib\sys\IStaticContent;
+use nulib\php\content\content;
+use nulib\php\content\IStaticContent;
 
 class ATag implements IStaticContent {
   function __construct(string $tag, $contents=null) {
diff --git a/php/tests/sys/impl/html.php b/php/tests/php/content/impl/html.php
similarity index 86%
rename from php/tests/sys/impl/html.php
rename to php/tests/php/content/impl/html.php
index cda5b67..fdb0b28 100644
--- a/php/tests/sys/impl/html.php
+++ b/php/tests/php/content/impl/html.php
@@ -1,5 +1,7 @@
 <?php
-namespace nulib\sys\impl;
+namespace nulib\php\content\impl;
+
+use nulib\php\content\impl\ATag;
 
 class html {
   const H1 = [self::class, "h1"];
diff --git a/php/tests/sys/funcTest.php b/php/tests/php/funcTest.php
similarity index 99%
rename from php/tests/sys/funcTest.php
rename to php/tests/php/funcTest.php
index d70a6b4..d7967bf 100644
--- a/php/tests/sys/funcTest.php
+++ b/php/tests/php/funcTest.php
@@ -12,7 +12,7 @@ namespace {
   function func_o1v($b=9, ...$c): array { return [$b, ...$c]; }
 }
 
-namespace nulib\sys {
+namespace nulib\php {
   use nulib\tests\TestCase;
 
   class funcTest extends TestCase {