[TASK] Implement Positionable

Closes #1207.

Author: JakeQZ

CHANGELOG.md

@@ -10,6 +10,12 @@ Please also have a look at our
 
 ### Added
 
+- Methods `getLineNumber` and `getColumnNumber` which return a nullable `int`
+  for the following classes:
+  `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
+  `Rule`, `DeclarationBlock, `RuleSet`, `CSSFunction`, `Value` (#1225)
+- `Positionable` interface for CSS items that may have an original position
+  (line and perhaps column number) in the parsed CSS (#1221)
 - Partial support for CSS Color Module Level 4:
     - `rgb` and `rgba`, and `hsl` and `hsla` are now aliases (#797}
     - Parse color functions that use the "modern" syntax (#800)
@@ -20,6 +26,9 @@ Please also have a look at our
 
 ### Changed
 
+- Implement `Positionable` in the following CSS item classes:
+  `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
+  `Rule`, `DeclarationBlock, `RuleSet`, `CSSFunction`, `Value` (#1225)
 - Initialize `KeyFrame` properties to sensible defaults (#1146)
 - Make `OutputFormat` `final` (#1128)
 - Make `Selector` a `Renderable` (#1017)
@@ -33,6 +42,13 @@ Please also have a look at our
 
 ### Deprecated
 
+- `getLineNo()` is deprecated in these classes (use `getLineNumber()` instead):
+  `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
+  `Rule`, `DeclarationBlock, `RuleSet`, `CSSFunction`, `Value` (#1225)
+- `Rule::getColNo()` is deprecated (use `getColumnNumber()` instead) (#1225)
+- Providing zero as the line number argument to `Rule::setPosition()` is
+  deprecated (pass `null` instead if there is no line number) (#1225)
+
 ### Removed
 
 - Remove `__toString()` (#1046)

src/CSSList/CSSList.php

@@ -10,6 +10,8 @@
 use Sabberworm\CSS\Parsing\SourceException;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
 use Sabberworm\CSS\Property\AtRule;
 use Sabberworm\CSS\Property\Charset;
 use Sabberworm\CSS\Property\CSSNamespace;
@@ -33,9 +35,10 @@
  * Note that `CSSListItem` extends both `Commentable` and `Renderable`,
  * so those interfaces must also be implemented by concrete subclasses.
  */
-abstract class CSSList implements CSSListItem
+abstract class CSSList implements CSSListItem, Positionable
 {
     use CommentContainer;
+    use Position;
 
     /**
      * @var array<int<0, max>, CSSListItem>
@@ -44,19 +47,12 @@ abstract class CSSList implements CSSListItem
      */
     protected $contents = [];
 
-    /**
-     * @var int<0, max>
-     *
-     * @internal since 8.8.0
-     */
-    protected $lineNumber;
-
     /**
      * @param int<0, max> $lineNumber
      */
     public function __construct(int $lineNumber = 0)
     {
-        $this->lineNumber = $lineNumber;
+        $this->setPosition($lineNumber);
     }
 
     /**
@@ -250,14 +246,6 @@ private static function identifierIs(string $identifier, string $match): bool
             ?: \preg_match("/^(-\\w+-)?$match$/i", $identifier) === 1;
     }
 
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
-    }
-
     /**
      * Prepends an item to the list of contents.
      */

src/Comment/Comment.php

@@ -6,15 +6,12 @@
 
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Renderable;
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
 
-class Comment implements Renderable
+class Comment implements Positionable, Renderable
 {
-    /**
-     * @var int<0, max>
-     *
-     * @internal since 8.8.0
-     */
-    protected $lineNumber;
+    use Position;
 
     /**
      * @var string
@@ -29,22 +26,14 @@ class Comment implements Renderable
     public function __construct(string $commentText = '', int $lineNumber = 0)
     {
         $this->commentText = $commentText;
-        $this->lineNumber = $lineNumber;
+        $this->setPosition($lineNumber);
     }
 
     public function getComment(): string
     {
         return $this->commentText;
     }
 
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
-    }
-
     public function setComment(string $commentText): void
     {
         $this->commentText = $commentText;

src/Parsing/SourceException.php

@@ -4,30 +4,22 @@
 
 namespace Sabberworm\CSS\Parsing;
 
-class SourceException extends \Exception
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
+
+class SourceException extends \Exception implements Positionable
 {
-    /**
-     * @var int<0, max>
-     */
-    private $lineNumber;
+    use Position;
 
     /**
      * @param int<0, max> $lineNumber
      */
     public function __construct(string $message, int $lineNumber = 0)
     {
-        $this->lineNumber = $lineNumber;
+        $this->setPosition($lineNumber);
         if ($lineNumber !== 0) {
             $message .= " [line no: $lineNumber]";
         }
         parent::__construct($message);
     }
-
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
-    }
 }

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;
+}

src/Property/CSSNamespace.php

@@ -6,15 +6,18 @@
 
 use Sabberworm\CSS\Comment\CommentContainer;
 use Sabberworm\CSS\OutputFormat;
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
 use Sabberworm\CSS\Value\CSSString;
 use Sabberworm\CSS\Value\URL;
 
 /**
  * `CSSNamespace` represents an `@namespace` rule.
  */
-class CSSNamespace implements AtRule
+class CSSNamespace implements AtRule, Positionable
 {
     use CommentContainer;
+    use Position;
 
     /**
      * @var CSSString|URL
@@ -26,11 +29,6 @@ class CSSNamespace implements AtRule
      */
     private $prefix;
 
-    /**
-     * @var int<0, max> $lineNumber
-     */
-    private $lineNumber;
-
     /**
      * @param CSSString|URL $url
      * @param int<0, max> $lineNumber
@@ -39,15 +37,7 @@ public function __construct($url, ?string $prefix = null, int $lineNumber = 0)
     {
         $this->url = $url;
         $this->prefix = $prefix;
-        $this->lineNumber = $lineNumber;
-    }
-
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
+        $this->setPosition($lineNumber);
     }
 
     /**

src/Property/Charset.php

@@ -6,6 +6,8 @@
 
 use Sabberworm\CSS\Comment\CommentContainer;
 use Sabberworm\CSS\OutputFormat;
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
 use Sabberworm\CSS\Value\CSSString;
 
 /**
@@ -16,37 +18,23 @@
  * - May only appear at the very top of a Document’s contents.
  * - Must not appear more than once.
  */
-class Charset implements AtRule
+class Charset implements AtRule, Positionable
 {
     use CommentContainer;
+    use Position;
 
     /**
      * @var CSSString
      */
     private $charset;
 
-    /**
-     * @var int<0, max>
-     *
-     * @internal since 8.8.0
-     */
-    protected $lineNumber;
-
     /**
      * @param int<0, max> $lineNumber
      */
     public function __construct(CSSString $charset, int $lineNumber = 0)
     {
         $this->charset = $charset;
-        $this->lineNumber = $lineNumber;
-    }
-
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
+        $this->setPosition($lineNumber);
     }
 
     /**