Add phpdoc platforms

Author: SerafimArts

Diff for: src/Parser.php

@@ -8,18 +8,6 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\MutableTagFactoryInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
-use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\ParamTag\ParamTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyReadTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyWriteTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\ReturnTag\ReturnTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\TemplateExtendsTag\TemplateExtendsTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\TemplateExtendsTag\TemplateImplementsTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\TemplateTag\TemplateCovariantTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\TemplateTag\TemplateTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\ThrowsTag\ThrowsTagFactory;
-use TypeLang\PHPDoc\DocBlock\Tag\VarTag\VarTagFactory;
 use TypeLang\PHPDoc\Exception\ParsingException;
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Comment\CommentParserInterface;
@@ -30,6 +18,8 @@
 use TypeLang\PHPDoc\Parser\SourceMap;
 use TypeLang\PHPDoc\Parser\Tag\RegexTagParser;
 use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
+use TypeLang\PHPDoc\Platform\PlatformInterface;
+use TypeLang\PHPDoc\Platform\StandardPlatform;
 
 class Parser implements ParserInterface
 {
@@ -41,36 +31,28 @@ class Parser implements ParserInterface
 
     private readonly MutableTagFactoryInterface $factories;
 
-    /**
-     * @param iterable<non-empty-string, TagFactoryInterface>|null $tags
-     */
-    public function __construct(?iterable $tags = null)
+    public function __construct(
+        public readonly PlatformInterface $platform = new StandardPlatform(),
+    ) {
+        $this->factories = new TagFactory($platform->getTags());
+        $this->tags = $this->createTagParser($this->factories);
+        $this->descriptions = $this->createDescriptionParser($this->tags);
+        $this->comments = $this->createCommentParser();
+    }
+
+    protected function createTagParser(TagFactoryInterface $factories): TagParserInterface
     {
-        $this->factories = new TagFactory($tags ?? self::createDefaultTags());
-        $this->tags = new RegexTagParser($this->factories);
-        $this->descriptions = new RegexDescriptionParser($this->tags);
-        $this->comments = new RegexCommentParser();
+        return new RegexTagParser($factories);
     }
 
-    /**
-     * @return iterable<non-empty-string, TagFactoryInterface>
-     */
-    private static function createDefaultTags(): iterable
+    protected function createDescriptionParser(TagParserInterface $tags): DescriptionParserInterface
+    {
+        return new RegexDescriptionParser($tags);
+    }
+
+    protected function createCommentParser(): CommentParserInterface
     {
-        yield 'method' => new MethodTagFactory();
-        yield 'param' => new ParamTagFactory();
-        yield 'property' => new PropertyTagFactory();
-        yield 'property-read' => new PropertyReadTagFactory();
-        yield 'property-write' => new PropertyWriteTagFactory();
-        yield 'return' => new ReturnTagFactory();
-        yield 'throws' => new ThrowsTagFactory();
-        yield 'var' => new VarTagFactory();
-        yield 'template' => new TemplateTagFactory();
-        yield 'template-implements' => $implements = new TemplateImplementsTagFactory();
-        yield 'implements' => $implements;
-        yield 'template-extends' => $extends = new TemplateExtendsTagFactory();
-        yield 'extends' => $extends;
-        yield 'template-covariant' => new TemplateCovariantTagFactory();
+        return new RegexCommentParser();
     }
 
     /**

Diff for: src/ParserInterface.php

@@ -4,13 +4,12 @@
 
 namespace TypeLang\PHPDoc;
 
-use JetBrains\PhpStorm\Language;
 use TypeLang\PHPDoc\DocBlock\DocBlock;
 
 interface ParserInterface
 {
     /**
      * @param string $docblock a string containing the DocBlock to parse
      */
-    public function parse(#[Language('PHP')] string $docblock): DocBlock;
+    public function parse(string $docblock): DocBlock;
 }

Diff for: src/Platform/CompoundPlatform.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Platform;
+
+final class CompoundPlatform implements PlatformInterface
+{
+    /**
+     * @var list<PlatformInterface>
+     */
+    public readonly array $platforms;
+
+    /**
+     * @param iterable<array-key, PlatformInterface> $platforms
+     */
+    public function __construct(iterable $platforms = [])
+    {
+        $this->platforms = match (true) {
+            $platforms instanceof \Traversable => \iterator_to_array($platforms, false),
+            \array_is_list($platforms) => $platforms,
+            default => \array_values($platforms),
+        };
+    }
+
+    public function getName(): string
+    {
+        if ($this->platforms === []) {
+            return 'empty';
+        }
+
+        $names = [];
+
+        foreach ($this->platforms as $platform) {
+            $names[] = $platform->getName();
+        }
+
+        return \implode(' & ', $names);
+    }
+
+    public function getTags(): iterable
+    {
+        foreach ($this->platforms as $platform) {
+            yield from $platform->getTags();
+        }
+    }
+}

Diff for: src/Platform/Platform.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Platform;
+
+use TypeLang\Parser\Parser as TypesParser;
+use TypeLang\Parser\ParserInterface as TypesParserInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+
+abstract class Platform implements PlatformInterface
+{
+    public function __construct(
+        protected readonly TypesParserInterface $types = new TypesParser(tolerant: true),
+    ) {
+        if ($this->types instanceof TypesParser && $this->types->tolerant === false) {
+            throw new \InvalidArgumentException('Tolerant parser mode required');
+        }
+    }
+
+    public function getTags(): iterable
+    {
+        foreach ($this->load($this->types) as $tag => $factory) {
+            if (\is_iterable($tag)) {
+                foreach ($tag as $name) {
+                    yield $name => $factory;
+                }
+            } else {
+                yield $tag => $factory;
+            }
+        }
+    }
+
+    /**
+     * @return iterable<non-empty-string|iterable<mixed, non-empty-string>, TagFactoryInterface>
+     */
+    abstract protected function load(TypesParserInterface $types): iterable;
+}

Diff for: src/Platform/PlatformInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Platform;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+
+interface PlatformInterface
+{
+    /**
+     * Platform name to display anywhere.
+     *
+     * @return non-empty-string
+     */
+    public function getName(): string;
+
+    /**
+     * Returns a list of registered tags for the specified platform.
+     *
+     * @return iterable<non-empty-string, TagFactoryInterface>
+     */
+    public function getTags(): iterable;
+}

Diff for: src/Platform/StandardPlatform.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Platform;
+
+use TypeLang\Parser\ParserInterface as TypesParserInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\ParamTag\ParamTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyReadTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyWriteTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\ReturnTag\ReturnTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\TemplateExtendsTag\TemplateExtendsTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\TemplateExtendsTag\TemplateImplementsTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\TemplateTag\TemplateCovariantTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\TemplateTag\TemplateTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\ThrowsTag\ThrowsTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\VarTag\VarTagFactory;
+
+final class StandardPlatform extends Platform
+{
+    public function getName(): string
+    {
+        return 'standard';
+    }
+
+    protected function load(TypesParserInterface $types): iterable
+    {
+        yield 'method' => new MethodTagFactory();
+        yield 'param' => new ParamTagFactory();
+        yield 'property' => new PropertyTagFactory();
+        yield 'property-read' => new PropertyReadTagFactory();
+        yield 'property-write' => new PropertyWriteTagFactory();
+        yield 'return' => new ReturnTagFactory();
+        yield 'throws' => new ThrowsTagFactory();
+        yield 'var' => new VarTagFactory();
+        yield 'template' => new TemplateTagFactory();
+        yield ['template-implements', 'implements'] => new TemplateImplementsTagFactory();
+        yield ['template-extends', 'extends'] => new TemplateExtendsTagFactory();
+        yield 'template-covariant' => new TemplateCovariantTagFactory();
+    }
+}