[TASK] Implement Positionable (#1225)

Closes #1207.

Author: JakeQZ

Diff for: 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 a 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)

Diff for: README.md

@@ -627,6 +627,9 @@ classDiagram
     class Renderable {
         <<interface>>
     }
+    class Positionable {
+        <<interface>>
+    }
     class CSSListItem {
         <<interface>>
     }
@@ -720,23 +723,30 @@ classDiagram
     RuleSet <|-- DeclarationBlock: inheritance
     Renderable <|-- CSSListItem: inheritance
     Commentable <|-- CSSListItem: inheritance
+    Positionable <|.. RuleSet: realization
     CSSListItem <|.. RuleSet: realization
     RuleSet <|-- AtRuleSet: inheritance
     AtRule <|.. AtRuleSet: realization
     Renderable <|.. Selector: realization
     Selector <|-- KeyframeSelector: inheritance
     CSSListItem <|-- AtRule: inheritance
+    Positionable <|.. Charset: realization
     AtRule <|.. Charset: realization
+    Positionable <|.. Import: realization
     AtRule <|.. Import: realization
+    Positionable <|.. CSSNamespace: realization
     AtRule <|.. CSSNamespace: realization
     Renderable <|.. Rule: realization
+    Positionable <|.. Rule: realization
     Commentable <|.. Rule: realization
     SourceException <|-- OutputException: inheritance
     UnexpectedTokenException <|-- UnexpectedEOFException: inheritance
     Exception <|-- SourceException: inheritance
+    Positionable <|.. SourceException: realization
     SourceException <|-- UnexpectedTokenException: inheritance
     CSSList <|-- CSSBlockList: inheritance
     CSSBlockList <|-- Document: inheritance
+    Positionable <|.. CSSList: realization
     CSSListItem <|.. CSSList: realization
     CSSList <|-- KeyFrame: inheritance
     AtRule <|.. KeyFrame: realization
@@ -749,12 +759,14 @@ classDiagram
     CSSFunction <|-- CalcFunction: inheritance
     ValueList <|-- LineName: inheritance
     Renderable <|.. Value: realization
+    Positionable <|.. Value: realization
     PrimitiveValue <|-- Size: inheritance
     PrimitiveValue <|-- CSSString: inheritance
     Value <|-- PrimitiveValue: inheritance
     ValueList <|-- CSSFunction: inheritance
     ValueList <|-- RuleValueList: inheritance
     Renderable <|.. Comment: realization
+    Positionable <|.. Comment: realization
 
     %% end of the generated part
 

Diff for: 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;
@@ -32,9 +34,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>
@@ -43,19 +46,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);
     }
 
     /**
@@ -249,14 +245,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.
      */

Diff for: 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;

Diff for: 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;
-    }
 }

Diff for: 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);
     }
 
     /**

Diff for: 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);
     }
 
     /**

Diff for: src/Property/Import.php

@@ -6,14 +6,17 @@
 
 use Sabberworm\CSS\Comment\CommentContainer;
 use Sabberworm\CSS\OutputFormat;
+use Sabberworm\CSS\Position\Position;
+use Sabberworm\CSS\Position\Positionable;
 use Sabberworm\CSS\Value\URL;
 
 /**
  * Class representing an `@import` rule.
  */
-class Import implements AtRule
+class Import implements AtRule, Positionable
 {
     use CommentContainer;
+    use Position;
 
     /**
      * @var URL
@@ -25,29 +28,14 @@ class Import implements AtRule
      */
     private $mediaQuery;
 
-    /**
-     * @var int<0, max>
-     *
-     * @internal since 8.8.0
-     */
-    protected $lineNumber;
-
     /**
      * @param int<0, max> $lineNumber
      */
     public function __construct(URL $location, ?string $mediaQuery, int $lineNumber = 0)
     {
         $this->location = $location;
         $this->mediaQuery = $mediaQuery;
-        $this->lineNumber = $lineNumber;
-    }
-
-    /**
-     * @return int<0, max>
-     */
-    public function getLineNo(): int
-    {
-        return $this->lineNumber;
+        $this->setPosition($lineNumber);
     }
 
     public function setLocation(URL $location): void