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
* implement logic for markdown
  * include checks for compliant strings for Markdown inputs
  * include transformation from the Refinery for rendering
* 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.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 ILIAS\Data\TextHandling;
+
+interface Markup
+{
+}

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

@@ -0,0 +1,27 @@
+<?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 ILIAS\Data\TextHandling\Markup;
+
+use ILIAS\Data\TextHandling\Markup;
+
+class Markdown implements Markup
+{
+}

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

@@ -0,0 +1,51 @@
+<?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 ILIAS\Data\TextHandling;
+
+use ILIAS\Data\TextHandling\Text\HTML;
+use ILIAS\Data\TextHandling\Text\PlainText;
+
+/**
+ * Methods in this interface should mostly be called by the according methods
+ * on `Text` instances, most consumer code shouldn't need to bother with `Shape`
+ * directly.
+ *
+ * Only exception is `fromString` which acts as an entrypoint into the logic
+ * of TextHandling.
+ */
+interface Shape
+{
+    /**
+     * @throws \InvalidArgumentException if $text is not compliant.
+     */
+    public function fromString(string $text): Text;
+
+    public function isRawStringCompliant(string $text): bool;
+    /**
+     * @throws \InvalidArgumentException if $text does not match format.
+     */
+    public function toHTML(Text $text): HTML;
+    /**
+     * @throws \InvalidArgumentException if $text does not match format.
+     */
+    public function toPlainText(Text $text): PlainText;
+    public function getMarkup(): Markup;
+}

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

@@ -0,0 +1,69 @@
+<?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 ILIAS\Data\TextHandling\Shape;
+
+use ILIAS\Data\TextHandling\Shape;
+use ILIAS\Data\TextHandling\Markup;
+use ILIAS\Data\TextHandling\Text;
+use ILIAS\Refinery;
+
+class Markdown implements Shape
+{
+    public function __construct(
+        protected Refinery\Transformation $markdown_to_html_transformation,
+    ) {
+    }
+
+    public function toHTML(Text $text): Text\HTML
+    {
+        if (!$text instanceof Text\Markdown) {
+            throw new \InvalidArgumentException("Text does not match format.");
+        }
+        return new Text\HTML(
+            $this->markdown_to_html_transformation->transform(
+                $text->getRawRepresentation()
+            )
+        );
+    }
+
+    public function toPlainText(Text $text): Text\PlainText
+    {
+        if (!$text instanceof Text\Markdown) {
+            throw new \InvalidArgumentException("Text does not match format.");
+        }
+        return new Text\PlainText($text->getRawRepresentation());
+    }
+
+    public function getMarkup(): Markup\Markdown
+    {
+        return new Markup\Markdown();
+    }
+
+    public function fromString(string $text): Text\Markdown
+    {
+        return new Text\Markdown($this, $text);
+    }
+
+    public function isRawStringCompliant(string $text): bool
+    {
+        return true;
+    }
+}

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 ILIAS\Data\TextHandling\Shape;
+
+use ILIAS\Data\TextHandling\Structure;
+use ILIAS\Data\TextHandling\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\SimpleDocumentMarkdown
+    {
+        return new 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 ILIAS\Data\TextHandling\Shape;
+
+use ILIAS\Data\TextHandling\Structure;
+use ILIAS\Data\TextHandling\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\WordOnlyMarkdown
+    {
+        return new 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 ILIAS\Data\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.php

@@ -0,0 +1,34 @@
+<?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 ILIAS\Data\TextHandling;
+
+interface Text
+{
+    public function getShape(): Shape;
+    public function getMarkup(): Markup;
+    /**
+     * @return Structure[]
+     */
+    public function getSupportedStructure(): array;
+    public function toHTML(): Text\HTML;
+    public function toPlainText(): Text\PlainText;
+    public function getRawRepresentation(): string;
+}