Add optional type and value content parsers

Author: Kirill Nesmeyanov

src/Tag/Content.php

@@ -4,10 +4,14 @@
 
 namespace TypeLang\PHPDoc\Tag;
 
+use TypeLang\Parser\Exception\ParserExceptionInterface;
 use TypeLang\Parser\Node\Stmt\TypeStatement;
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\Exception\InvalidTagException;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\Content\OptionalTypeParserApplicator;
+use TypeLang\PHPDoc\Tag\Content\ValueApplicator;
+use TypeLang\PHPDoc\Tag\Content\OptionalValueApplicator;
 use TypeLang\PHPDoc\Tag\Content\OptionalVariableNameApplicator;
 use TypeLang\PHPDoc\Tag\Content\TypeParserApplicator;
 use TypeLang\PHPDoc\Tag\Content\VariableNameApplicator;
@@ -67,6 +71,14 @@ public function nextType(string $tag, TypesParserInterface $parser): TypeStateme
         return $this->apply(new TypeParserApplicator($tag, $parser));
     }
 
+    /**
+     * @api
+     */
+    public function nextOptionalType(TypesParserInterface $parser): ?TypeStatement
+    {
+        return $this->apply(new OptionalTypeParserApplicator($parser));
+    }
+
     /**
      * @api
      * @param non-empty-string $tag
@@ -86,6 +98,32 @@ public function nextOptionalVariable(): ?string
         return $this->apply(new OptionalVariableNameApplicator());
     }
 
+    /**
+     * @template T of non-empty-string
+     *
+     * @api
+     * @param non-empty-string $tag
+     * @param T $value
+     * @return T
+     */
+    public function nextValue(string $tag, string $value): string
+    {
+        return $this->apply(new ValueApplicator($tag, $value));
+    }
+
+    /**
+     * @template T of non-empty-string
+     *
+     * @api
+     * @param non-empty-string $tag
+     * @param T $value
+     * @return T|null
+     */
+    public function nextOptionalValue(string $value): ?string
+    {
+        return $this->apply(new OptionalValueApplicator($value));
+    }
+
     /**
      * @template T of mixed
      * @param callable(Content):T $applicator

src/Tag/Content/OptionalTypeParserApplicator.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag\Content;
+
+use TypeLang\Parser\Exception\ParserExceptionInterface;
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+use TypeLang\Parser\ParserInterface as TypesParserInterface;
+use TypeLang\PHPDoc\Exception\InvalidTagException;
+use TypeLang\PHPDoc\Tag\Content;
+
+/**
+ * @template-extends Applicator<TypeStatement|null>
+ */
+final class OptionalTypeParserApplicator extends Applicator
+{
+    /**
+     * @param non-empty-string $tag
+     */
+    public function __construct(
+        private readonly TypesParserInterface $parser,
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     *
+     * @throws \Throwable
+     * @throws InvalidTagException
+     */
+    public function __invoke(Content $lexer): ?TypeStatement
+    {
+        try {
+            $type = $this->parser->parse($lexer->value);
+        } catch (ParserExceptionInterface $e) {
+            return null;
+        }
+
+        /**
+         * @psalm-suppress MixedArgument
+         * @psalm-suppress NoInterfaceProperties
+         */
+        $lexer->shift($this->parser->lastProcessedTokenOffset);
+
+        return $type;
+    }
+}

src/Tag/Content/OptionalValueApplicator.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag\Content;
+
+use TypeLang\PHPDoc\Tag\Content;
+
+/**
+ * @template T of non-empty-string
+ * @template-extends Applicator<T|null>
+ */
+final class OptionalValueApplicator extends Applicator
+{
+    /**
+     * @param T $value
+     */
+    public function __construct(
+        private readonly string $value,
+    ) {}
+
+    /**
+     * @return T|null
+     */
+    public function __invoke(Content $lexer): ?string
+    {
+        if (!\str_starts_with($lexer->value, $this->value)) {
+            return null;
+        }
+
+        $expectedLength = \strlen($this->value);
+
+        // In case of end of string
+        if ($expectedLength === \strlen(\rtrim($lexer->value))) {
+            return $this->apply($lexer);
+        }
+
+        // In case of separated by whitespace
+        if (\ctype_space($lexer->value[$expectedLength])) {
+            return $this->apply($lexer);
+        }
+
+        return null;
+    }
+
+    /**
+     * @return T
+     */
+    private function apply(Content $lexer): string
+    {
+        $lexer->shift(\strlen($this->value));
+
+        return $this->value;
+    }
+}

src/Tag/Content/TypeParserApplicator.php

@@ -44,6 +44,7 @@ public function __invoke(Content $lexer): TypeStatement
 
         /**
          * @psalm-suppress MixedArgument
+         * @psalm-suppress NoInterfaceProperties
          */
         $lexer->shift($this->parser->lastProcessedTokenOffset);
 

src/Tag/Content/ValueApplicator.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag\Content;
+
+use TypeLang\PHPDoc\Exception\InvalidTagException;
+use TypeLang\PHPDoc\Tag\Content;
+
+/**
+ * @template T of non-empty-string
+ * @template-extends Applicator<T>
+ */
+final class ValueApplicator extends Applicator
+{
+    private readonly OptionalValueApplicator $identifier;
+
+    /**
+     * @param non-empty-string $tag
+     * @param T $value
+     */
+    public function __construct(
+        private readonly string $tag,
+        private readonly string $value
+    ) {
+        $this->identifier = new OptionalValueApplicator($value);
+    }
+
+    /**
+     * @return T
+     *
+     * @throws InvalidTagException
+     */
+    public function __invoke(Content $lexer): string
+    {
+        return ($this->identifier)($lexer)
+            ?? throw $lexer->getTagException(\sprintf(
+                'Tag @%s contains an incorrect identifier value "%s"',
+                $this->tag,
+                $this->value,
+            ));
+    }
+}

src/Tag/Description.php

@@ -25,6 +25,9 @@ public function __construct(
         $this->bootTagProvider($tags);
     }
 
+    /**
+     * @return ($description is DescriptionInterface ? DescriptionInterface : self)
+     */
     public static function fromStringable(string|\Stringable $description): DescriptionInterface
     {
         if ($description instanceof DescriptionInterface) {
@@ -34,6 +37,9 @@ public static function fromStringable(string|\Stringable $description): Descript
         return new self($description);
     }
 
+    /**
+     * @return ($description is DescriptionInterface ? DescriptionInterface : self|null)
+     */
     public static function fromStringableOrNull(string|\Stringable|null $description): ?DescriptionInterface
     {
         if ($description === null) {