Initial commit

Author: drmad

Diff for: .gitignore

@@ -0,0 +1,2 @@
+composer.lock
+vendor/

Diff for: .phpunit.result.cache

@@ -0,0 +1 @@
+{"version":1,"defects":{"TextFromDocCommentTest::testSingleLine":8,"TextFromDocCommentTest::testMultiLine":7,"TextFromDocCommentTest::testMultiParagraph":7,"TextFromDocCommentTest::testEmptyDocBlock":8,"TextFromDocCommentTest::testJoinedMultiLine":7,"TextFromDocCommentTest::testJoinedMultiParagraph":7},"times":{"TextFromDocCommentTest::testEmptyDocBlock":0,"TextFromDocCommentTest::testSingleLine":0,"TextFromDocCommentTest::testMultiLine":0,"TextFromDocCommentTest::testMultiParagraph":0,"TextFromDocCommentTest::testJoinedMultiLine":0,"TextFromDocCommentTest::testJoinedMultiParagraph":0}}

Diff for: README.md

@@ -0,0 +1,47 @@
+# Vendimia helper classes
+
+## `Vendimia\Helper\TextFromDocComment`
+
+Process a DocComment, (perhaps obtained with `Reflection*::getDocComment()` method), obtaining only the text with preceding or trailing spaces or empty lines removed. Also remove an initial `*` on each line.
+
+### `public string $text`
+
+Processed text, also obtainable by using the class in a string context.
+
+### `public function __construct(string $doc_comment, bool $merge_lines = true)`
+
+* `string $doc_comment`: Original doc comment.
+
+* `bool $merge_lines`: `true` merges continuous non-empty lines as one, joined by a single empty space. `false` returns the lines as is.
+
+### Example
+
+```php
+use Vendimia\Helper\TextFromDocComment;
+
+require __DIR__ . '/vendor/autoload.php';
+
+/**
+ * This is a dummy function.
+ *
+ * Its purpose is to hold a multiline doc comment to test the
+ * Vendimia\Helper\TextFromDocComment class.
+ */
+function dummy()
+{
+
+}
+
+echo (string)new TextFromDocComment(
+    new ReflectionFunction(dummy(...))->getDocComment()
+);
+```
+
+This outputs:
+
+```
+This is a dummy function.
+Its purpose is to hold a multiline doc comment to test the Vendimia\Helper\TextFromDocComment class. 
+```
+
+On PHP prior to 8.4, you must enclose  `new ReflectionFunction(dummy(...))` on parenthesis.

Diff for: composer.json

@@ -0,0 +1,22 @@
+{
+    "name": "vendimia/helper",
+    "description": "Assorted helper classes",
+    "license": "GPL-3.0-or-later",
+    "keywords": ["php", "vendimia", "orm"],
+    "require": {
+        "php": ">=8.1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Vendimia\\Helper\\": "src"
+        }
+    },
+    "authors": [
+        {
+            "name": "Oliver Etchebarne",
+            "email": "[email protected]",
+            "homepage": "https://drmad.org",
+            "role": "developer"
+        }
+    ]
+}

Diff for: phpunit.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpunit bootstrap="tests/bootstrap.php">
+    <testsuites>
+        <testsuite name="all">
+        <directory>tests/</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

Diff for: src/TextFromDocComment.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace Vendimia\Helper;
+
+use Stringable;
+
+/**
+ * Extract the text from a DocComment block.
+ *
+ * Each
+ */
+class TextFromDocComment implements Stringable
+{
+    /** Extracted text */
+    public string $text = '';
+
+    public function __construct(
+        string $doc_comment,
+        bool $merge_lines = true
+    )
+    {
+        $result = [];
+        $lines = explode("\n", $doc_comment);
+
+        // Si solo hay una línea, removemos los caracteres de ámbos lados
+        if (count($lines) == 1) {
+            $this->text = trim($doc_comment, '/* ');
+            return;
+        }
+
+        $last_line = '';
+
+        foreach ($lines as $line) {
+            $pline = trim($line);
+
+            // Si la línea empieza con un '/**', lo eliminamos
+            if (str_starts_with($pline, '/**')) {
+                $pline = substr($pline, 3);
+
+                // Si el resultado es vacío, lo ignoramos
+                if (!$pline) {
+                    continue;
+                }
+            }
+
+            // Si la línea acaba con un */, lo eliminamos
+            if (str_ends_with($pline, '*/')) {
+                $pline = substr($pline, 1, -2);
+            }
+
+            // Si la línea empieza con un '*', lo eliminamos
+            if (str_starts_with($pline, '*')) {
+                $pline = trim(substr($pline, 1));
+            }
+
+            // Líneas vacías añaden un nuevo párrafo.
+
+            if ($merge_lines) {
+                if ($pline == "") {
+                    $last_line = trim($last_line);
+                    if ($last_line) {
+                        $result[] = $last_line;
+                        $last_line = '';
+                    }
+                } else {
+                    $last_line .= $pline . ' ';
+                }
+            } else {
+                $result[] = trim($pline);
+            }
+        }
+        $this->text = trim(join("\n", $result));
+    }
+
+    public function __toString(): string
+    {
+        return $this->text;
+    }
+}

Diff for: tests/TextFromDocCommentTest.php

@@ -0,0 +1,79 @@
+<?php declare(strict_types=1);
+use PHPUnit\Framework\TestCase;
+use Vendimia\Helper\TextFromDocComment;
+
+final class TextFromDocCommentTest extends TestCase
+{
+    public function testEmptyDocBlock(): void
+    {
+        $this->assertEquals(
+            (new TextFromDocComment('/** */'))->text,
+            ''
+        );
+    }
+
+    public function testSingleLine(): void
+    {
+        $this->assertEquals(
+            'Este es un DocComment',
+            (new TextFromDocComment('/** Este es un DocComment */'))->text,
+        );
+    }
+
+    public function testJoinedMultiLine(): void
+    {
+        $doc_comment = <<<EOF
+        /**
+         * Extract the text from a DocComment block, removing asterisk and trailing
+         * blank lines
+         */
+        EOF;
+
+        $this->assertEquals(
+            "Extract the text from a DocComment block, removing asterisk and trailing blank lines",
+            (new TextFromDocComment($doc_comment))->text,
+        );
+    }
+
+    public function testMultiLine(): void
+    {
+        $doc_comment = <<<EOF
+        /**
+         * Extract the text from a DocComment block, removing asterisk and trailing
+         * blank lines.
+         */
+        EOF;
+
+        $this->assertEquals(
+            <<<EOF
+            Extract the text from a DocComment block, removing asterisk and trailing
+            blank lines.
+            EOF,
+            (new TextFromDocComment($doc_comment, merge_lines: false))->text,
+        );
+    }
+
+    public function testJoinedMultiParagraph(): void
+    {
+        $doc_comment = <<<'EOF'
+        /**
+         * Extract the text from a DocComment block.
+         *
+         * This is a sample paragraph that should be returned
+         * in one single line.
+         *
+         * Other single-line paragraphs should work, also.
+         *
+         */
+        EOF;
+
+        $this->assertEquals(
+            <<<'EOF'
+            Extract the text from a DocComment block.
+            This is a sample paragraph that should be returned in one single line.
+            Other single-line paragraphs should work, also.
+            EOF,
+            (new TextFromDocComment($doc_comment))->text,
+        );
+    }
+}

Diff for: tests/bootstrap.php

@@ -0,0 +1,3 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';