Merge pull request #136 from enumag/list-type

Add list pseudo-type

Author: jaapio

src/PseudoTypes/List_.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\PseudoTypes;
+
+use phpDocumentor\Reflection\PseudoType;
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\Types\Array_;
+use phpDocumentor\Reflection\Types\Integer;
+use phpDocumentor\Reflection\Types\Mixed_;
+
+/**
+ * Value Object representing the type 'list'.
+ *
+ * @psalm-immutable
+ */
+final class List_ extends Array_ implements PseudoType
+{
+    public function underlyingType(): Type
+    {
+        return new Array_();
+    }
+
+    public function __construct(?Type $valueType = null)
+    {
+        parent::__construct($valueType, new Integer());
+    }
+
+    /**
+     * Returns a rendered output of the Type as it would be used in a DocBlock.
+     */
+    public function __toString(): string
+    {
+        if ($this->valueType instanceof Mixed_) {
+            return 'list';
+        }
+
+        return 'list<' . $this->valueType . '>';
+    }
+}

src/TypeResolver.php

@@ -26,6 +26,7 @@
 use phpDocumentor\Reflection\Types\InterfaceString;
 use phpDocumentor\Reflection\Types\Intersection;
 use phpDocumentor\Reflection\Types\Iterable_;
+use phpDocumentor\Reflection\PseudoTypes\List_;
 use phpDocumentor\Reflection\Types\Nullable;
 use phpDocumentor\Reflection\Types\Object_;
 use phpDocumentor\Reflection\Types\String_;
@@ -110,6 +111,7 @@ final class TypeResolver
         'parent' => Types\Parent_::class,
         'iterable' => Types\Iterable_::class,
         'never' => Types\Never_::class,
+        'list' => PseudoTypes\List_::class,
     ];
 
     /**
@@ -521,10 +523,11 @@ private function resolveCollection(ArrayIterator $tokens, Type $classType, Conte
     {
         $isArray    = ((string) $classType === 'array');
         $isIterable = ((string) $classType === 'iterable');
+        $isList     = ((string) $classType === 'list');
 
         // allow only "array", "iterable" or class name before "<"
         if (
-            !$isArray && !$isIterable
+            !$isArray && !$isIterable && !$isList
             && (!$classType instanceof Object_ || $classType->getFqsen() === null)
         ) {
             throw new RuntimeException(
@@ -538,7 +541,7 @@ private function resolveCollection(ArrayIterator $tokens, Type $classType, Conte
         $keyType   = null;
 
         $token = $tokens->current();
-        if ($token !== null && trim($token) === ',') {
+        if ($token !== null && trim($token) === ',' && !$isList) {
             // if we have a comma, then we just parsed the key type, not the value type
             $keyType = $valueType;
             if ($isArray) {
@@ -596,6 +599,10 @@ private function resolveCollection(ArrayIterator $tokens, Type $classType, Conte
             return new Iterable_($valueType, $keyType);
         }
 
+        if ($isList) {
+            return new List_($valueType);
+        }
+
         if ($classType instanceof Object_) {
             return $this->makeCollectionFromObject($classType, $valueType, $keyType);
         }

src/Types/Array_.php

@@ -24,6 +24,6 @@
  *
  * @psalm-immutable
  */
-final class Array_ extends AbstractList
+class Array_ extends AbstractList
 {
 }

tests/unit/CollectionResolverTest.php

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Reflection;
 
+use phpDocumentor\Reflection\PseudoTypes\List_;
 use phpDocumentor\Reflection\Types\Array_;
 use phpDocumentor\Reflection\Types\Collection;
 use phpDocumentor\Reflection\Types\Context;
@@ -297,4 +298,28 @@ public function testResolvingCollectionAsArray(): void
         $this->assertInstanceOf(Types\Float_::class, $valueType);
         $this->assertInstanceOf(Types\String_::class, $keyType);
     }
+
+    /**
+     * @uses \phpDocumentor\Reflection\Types\Context
+     * @uses \phpDocumentor\Reflection\Types\String_
+     *
+     * @covers ::__construct
+     * @covers ::resolve
+     */
+    public function testResolvingList(): void
+    {
+        $fixture = new TypeResolver();
+
+        $resolvedType = $fixture->resolve('list<string>', new Context(''));
+
+        $this->assertInstanceOf(List_::class, $resolvedType);
+        $this->assertSame('list<string>', (string) $resolvedType);
+
+        $valueType = $resolvedType->getValueType();
+
+        $keyType = $resolvedType->getKeyType();
+
+        $this->assertInstanceOf(Types\String_::class, $valueType);
+        $this->assertInstanceOf(Types\Integer::class, $keyType);
+    }
 }

tests/unit/PseudoTypes/ListTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\PseudoTypes;
+
+use phpDocumentor\Reflection\Types\Compound;
+use phpDocumentor\Reflection\Types\Integer;
+use phpDocumentor\Reflection\Types\Mixed_;
+use phpDocumentor\Reflection\Types\String_;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversDefaultClass \phpDocumentor\Reflection\PseudoTypes\List_
+ */
+class ListTest extends TestCase
+{
+    /**
+     * @dataProvider provideArrays
+     * @covers ::__toString
+     */
+    public function testArrayStringifyCorrectly(List_ $array, string $expectedString): void
+    {
+        $this->assertSame($expectedString, (string) $array);
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function provideArrays(): array
+    {
+        return [
+            'simple list' => [new List_(), 'list'],
+            'list of mixed' => [new List_(new Mixed_()), 'list'],
+            'list of single type' => [new List_(new String_()), 'list<string>'],
+            'list of compound type' => [new List_(new Compound([new Integer(), new String_()])), 'list<int|string>'],
+        ];
+    }
+}

tests/unit/TypeResolverTest.php

@@ -759,6 +759,7 @@ public function provideKeywords(): array
             ['iterable', Types\Iterable_::class],
             ['never', Types\Never_::class],
             ['literal-string', PseudoTypes\LiteralString::class],
+            ['list', PseudoTypes\List_::class],
         ];
     }