TextHandling: implement a tool to solve string-based text handling pr…

…oblems.

- create three layers (Markup, Shape and Text) in `Data/src/TextHandling`
--- include classes accordingly
--- declare possible structures via enum
--- include checks for compliant strings for Markdown inputs
- write PHPUnit Tests

You can read more in the [Text Handling Development Documentation](https://github.com/ILIAS-eLearning/ILIAS/blob/trunk/docs/development/text-handling.md)

components/ILIAS/Data/src/TextHandling/Markup/HTML.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Markup;
+
+class HTML implements Markup
+{
+}

components/ILIAS/Data/src/TextHandling/Markup/Markup.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Markup;
+
+interface Markup
+{
+}

components/ILIAS/Data/src/TextHandling/Shape/Markdown.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Shape;
+
+use Data\src\TextHandling\Text\HTML;
+use Data\src\TextHandling\Text\PlainText;
+use Data\src\TextHandling\Markup\Markup;
+use Data\src\TextHandling\Text\Text;
+use ILIAS\Refinery\Factory;
+
+class Markdown extends Shape
+{
+    public function __construct(
+        protected Factory $refinery,
+        protected Markup $markup
+    ) {
+        $this->refinery = $refinery;
+        $this->markup = $this->markup;
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public function toHTML($text): HTML
+    {
+        if (!is_string($text)) {
+            throw new \InvalidArgumentException("Text does not match format.");
+        }
+        return new HTML($this->refinery->string()->markdown()->toHTML()->transform($text));
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public function toPlainText($text): PlainText
+    {
+        if (!is_string($text)) {
+            throw new \InvalidArgumentException("Text does not match format.");
+        }
+        return new PlainText($text);
+    }
+
+    public function getMarkup(): Markup
+    {
+        return $this->markup;
+    }
+
+    public function fromString(string $text): Text
+    {
+        return new \Data\src\TextHandling\Text\Markdown($this, $text);
+    }
+
+    public function isRawStringCompliant(string $text): bool
+    {
+        return true;
+    }
+}

components/ILIAS/Data/src/TextHandling/Shape/Shape.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Shape;
+
+use Data\src\TextHandling\Text\HTML;
+use Data\src\TextHandling\Text\PlainText;
+use Data\src\TextHandling\Text\Text;
+use Data\src\TextHandling\Markup\Markup;
+
+abstract class Shape
+{
+    /**
+     * @throws \InvalidArgumentException if $text does not match format.
+     */
+    abstract public function toHTML($text): HTML;
+
+    /**
+     * @throws \InvalidArgumentException if $text does not match format.
+     */
+    abstract public function toPlainText($text): PlainText;
+    abstract public function getMarkup(): Markup;
+    abstract public function fromString(string $text): Text;
+    abstract public function isRawStringCompliant(string $text): bool;
+}

components/ILIAS/Data/src/TextHandling/Shape/SimpleDocumentMarkdown.php

@@ -0,0 +1,72 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Shape;
+
+use Data\src\TextHandling\Structure;
+use Data\src\TextHandling\Text\Text;
+
+class SimpleDocumentMarkdown extends Markdown
+{
+    /**
+     * @return mixed[] consts from Structure
+     */
+    public function getSupportedStructure(): array
+    {
+        return [
+            Structure::BOLD,
+            Structure::ITALIC,
+            Structure::HEADING_1,
+            Structure::HEADING_2,
+            Structure::HEADING_3,
+            Structure::HEADING_4,
+            Structure::HEADING_5,
+            Structure::HEADING_6,
+            Structure::UNORDERED_LIST,
+            Structure::ORDERED_LIST,
+            Structure::PARAGRAPH,
+            Structure::LINK,
+            Structure::BLOCKQUOTE,
+            Structure::CODE
+        ];
+    }
+
+    public function fromString(string $text): Text
+    {
+        return new \Data\src\TextHandling\Text\SimpleDocumentMarkdown($this, $text);
+    }
+
+    public function isRawStringCompliant(string $text): bool
+    {
+        $structure_patterns = [
+            '\!\[(.)*\]\((.)+\)',   // images ![](url)
+            '\!\[(.)+\]',           // images ![][url]
+            '\[(.)*\]\:(.)+'        // images []:url
+        ];
+
+        foreach ($structure_patterns as $pattern) {
+            if (mb_ereg_match($pattern, $text)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

components/ILIAS/Data/src/TextHandling/Shape/WordOnlyMarkdown.php

@@ -0,0 +1,72 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Shape;
+
+use Data\src\TextHandling\Structure;
+use Data\src\TextHandling\Text\Text;
+
+class WordOnlyMarkdown extends SimpleDocumentMarkdown
+{
+    /**
+     * @return mixed[] consts from Structure
+     */
+    public function getSupportedStructure(): array
+    {
+        return [
+            Structure::BOLD,
+            Structure::ITALIC
+        ];
+    }
+
+    public function fromString(string $text): Text
+    {
+        return new \Data\src\TextHandling\Text\WordOnlyMarkdown($this, $text);
+    }
+
+    public function isRawStringCompliant(string $text): bool
+    {
+        $structure_patterns = [
+            '^(\#){1,6}(\ )',       // headings 1 - 6
+            '^(\- )',               // unordered list
+            '^(\* )',               // unordered list
+            '^(\+ )',               // unordered list
+            '^([0-9]+)(\.\ )',      // ordered list
+            '(\ ){2}',              // paragraph via space
+            '(\\\)',                // paragraph
+            '\[(.)*\]\((.)+\)',     // link [title](url)
+            '\[(.)*\]\([.]+\)',     // link [id][url]
+            '\[(.)*\]\:(.)+',       // link [id]:url
+            '\!\[(.)*\]\((.)+\)',   // images ![](url)
+            '\!\[(.)+\]',           // images ![][url]
+            '\[(.)*\]\:(.)+',       // images []:url
+            '^(\>)+',               // blockquote
+            '(\`)'                  // code only
+        ];
+
+        foreach ($structure_patterns as $pattern) {
+            if (mb_ereg_match($pattern, $text)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

components/ILIAS/Data/src/TextHandling/Structure.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling;
+
+enum Structure
+{
+    // heading 1-6 are cases for <h1> to <h6>
+    case HEADING_1;
+    case HEADING_2;
+    case HEADING_3;
+    case HEADING_4;
+    case HEADING_5;
+    case HEADING_6;
+    case BOLD;
+    case ITALIC;
+    case UNORDERED_LIST;
+    case ORDERED_LIST;
+    case LINK;
+    case PARAGRAPH;
+    case BLOCKQUOTE;
+    case CODE;
+}

components/ILIAS/Data/src/TextHandling/Text/HTML.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace Data\src\TextHandling\Text;
+
+class HTML
+{
+    public function __construct(
+        protected string $html_text = ""
+    ) {
+        $this->html_text = $html_text;
+    }
+}