[TASK] Add Positionable interface and implementing trait

src/Position/Position.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Position;
+
+/**
+ * Provides a standard reusable implementation of `Positionable`.
+ *
+ * @internal
+ *
+ * @phpstan-require-implements Positionable
+ */
+trait Position
+{
+    /**
+     * @var int<1, max>|null
+     */
+    protected $lineNumber;
+
+    /**
+     * @var int<0, max>|null
+     */
+    protected $columnNumber;
+
+    /**
+     * @return int<1, max>|null
+     */
+    public function getLineNumber(): ?int
+    {
+        return $this->lineNumber;
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    public function getLineNo(): int
+    {
+        return $this->getLineNumber() ?? 0;
+    }
+
+    /**
+     * @return int<0, max>|null
+     */
+    public function getColumnNumber(): ?int
+    {
+        return $this->columnNumber;
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    public function getColNo(): int
+    {
+        return $this->getColumnNumber() ?? 0;
+    }
+
+    /**
+     * @param int<0, max>|null $lineNumber
+     * @param int<0, max>|null $columnNumber
+     */
+    public function setPosition(?int $lineNumber, ?int $columnNumber = null): void
+    {
+        // The conditional is for backwards compatibility (backcompat); `0` will not be allowed in future.
+        $this->lineNumber = $lineNumber !== 0 ? $lineNumber : null;
+        $this->columnNumber = $columnNumber;
+    }
+}

src/Position/Positionable.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Position;
+
+/**
+ * Represents a CSS item that may have a position in the source CSS document (line number and possibly column number).
+ *
+ * A standard implementation of this interface is available in the `Position` trait.
+ */
+interface Positionable
+{
+    /**
+     * @return int<1, max>|null
+     */
+    public function getLineNumber(): ?int;
+
+    /**
+     * @deprecated in version 9.0.0, will be removed in v10.0. Use `getLineNumber()` instead.
+     *
+     * @return int<0, max>
+     */
+    public function getLineNo(): int;
+
+    /**
+     * @return int<0, max>|null
+     */
+    public function getColumnNumber(): ?int;
+
+    /**
+     * @deprecated in version 9.0.0, will be removed in v10.0. Use `getColumnNumber()` instead.
+     *
+     * @return int<0, max>
+     */
+    public function getColNo(): int;
+
+    /**
+     * @param int<0, max>|null $lineNumber
+     *        Providing zero for this parameter is deprecated in version 9.0.0, and will not be supported from v10.0.
+     *        Use `null` instead when no line number is available.
+     * @param int<0, max>|null $columnNumber
+     */
+    public function setPosition(?int $lineNumber, ?int $columnNumber = null): void;
+}

tests/Unit/Position/Fixtures/ConcretePosition.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Position\Fixtures;
+
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
+
+final class ConcretePosition implements Positionable
+{
+    use Position;
+}

tests/Unit/Position/PositionTest.php

@@ -0,0 +1,194 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Position;
+
+use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\Tests\Unit\Position\Fixtures\ConcretePosition;
+use TRegx\DataProvider\DataProviders;
+
+/**
+ * @covers \Sabberworm\CSS\Position\Position
+ */
+final class PositionTest extends TestCase
+{
+    /**
+     * @var ConcretePosition
+     */
+    private $subject;
+
+    protected function setUp(): void
+    {
+        $this->subject = new ConcretePosition();
+    }
+
+    /**
+     * @test
+     */
+    public function getLineNumberInitiallyReturnsNull(): void
+    {
+        self::assertNull($this->subject->getLineNumber());
+    }
+
+    /**
+     * @test
+     */
+    public function getColumnNumberInitiallyReturnsNull(): void
+    {
+        self::assertNull($this->subject->getColumnNumber());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: int<1, max>}>
+     */
+    public function provideLineNumber(): array
+    {
+        return [
+            'line 1' => [1],
+            'line 42' => [42],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param int<1, max> $lineNumber
+     *
+     * @dataProvider provideLineNumber
+     */
+    public function setPositionOnVirginSetsLineNumber(int $lineNumber): void
+    {
+        $this->subject->setPosition($lineNumber);
+
+        self::assertSame($lineNumber, $this->subject->getLineNumber());
+    }
+
+    /**
+     * @test
+     *
+     * @param int<1, max> $lineNumber
+     *
+     * @dataProvider provideLineNumber
+     */
+    public function setPositionSetsNewLineNumber(int $lineNumber): void
+    {
+        $this->subject->setPosition(99);
+
+        $this->subject->setPosition($lineNumber);
+
+        self::assertSame($lineNumber, $this->subject->getLineNumber());
+    }
+
+    /**
+     * @test
+     */
+    public function setPositionWithNullClearsLineNumber(): void
+    {
+        $this->subject->setPosition(99);
+
+        $this->subject->setPosition(null);
+
+        self::assertNull($this->subject->getLineNumber());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: int<0, max>}>
+     */
+    public function provideColumnNumber(): array
+    {
+        return [
+            'column 0' => [0],
+            'column 14' => [14],
+            'column 39' => [39],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param int<0, max> $columnNumber
+     *
+     * @dataProvider provideColumnNumber
+     */
+    public function setPositionOnVirginSetsColumnNumber(int $columnNumber): void
+    {
+        $this->subject->setPosition(1, $columnNumber);
+
+        self::assertSame($columnNumber, $this->subject->getColumnNumber());
+    }
+
+    /**
+     * @test
+     *
+     * @dataProvider provideColumnNumber
+     */
+    public function setPositionSetsNewColumnNumber(int $columnNumber): void
+    {
+        $this->subject->setPosition(1, 99);
+
+        $this->subject->setPosition(2, $columnNumber);
+
+        self::assertSame($columnNumber, $this->subject->getColumnNumber());
+    }
+
+    /**
+     * @test
+     */
+    public function setPositionWithoutColumnNumberClearsColumnNumber(): void
+    {
+        $this->subject->setPosition(1, 99);
+
+        $this->subject->setPosition(2);
+
+        self::assertNull($this->subject->getColumnNumber());
+    }
+
+    /**
+     * @test
+     */
+    public function setPositionWithNullForColumnNumberClearsColumnNumber(): void
+    {
+        $this->subject->setPosition(1, 99);
+
+        $this->subject->setPosition(2, null);
+
+        self::assertNull($this->subject->getColumnNumber());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: int<1, max>, 1: int<0, max>}>
+     */
+    public function provideLineAndColumnNumber(): array
+    {
+        return DataProviders::cross($this->provideLineNumber(), $this->provideColumnNumber());
+    }
+
+    /**
+     * @test
+     *
+     * @dataProvider provideLineAndColumnNumber
+     */
+    public function setPositionOnVirginSetsLineAndColumnNumber(int $lineNumber, int $columnNumber): void
+    {
+        $this->subject->setPosition($lineNumber, $columnNumber);
+
+        self::assertSame($lineNumber, $this->subject->getLineNumber());
+        self::assertSame($columnNumber, $this->subject->getColumnNumber());
+    }
+
+    /**
+     * @test
+     *
+     * @dataProvider provideLineAndColumnNumber
+     */
+    public function setPositionSetsNewLineAndColumnNumber(int $lineNumber, int $columnNumber): void
+    {
+        $this->subject->setPosition(98, 99);
+
+        $this->subject->setPosition($lineNumber, $columnNumber);
+
+        self::assertSame($lineNumber, $this->subject->getLineNumber());
+        self::assertSame($columnNumber, $this->subject->getColumnNumber());
+    }
+}