Add NoDiscard attributes

psalm.xml

@@ -14,4 +14,7 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <issueHandlers>
+        <UndefinedAttributeClass errorLevel="suppress" />
+    </issueHandlers>
 </psalm>

src/Attribute.php

@@ -26,6 +26,7 @@ private function __construct(
      *
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function of(string $name, string $value = ''): self
     {
         return new self(null, $name, $value);
@@ -37,6 +38,7 @@ public static function of(string $name, string $value = ''): self
      * @param non-empty-string $namespace
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public static function namespaced(
         string $namespace,
         string $name,
@@ -48,6 +50,7 @@ public static function namespaced(
     /**
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(string $name, string $value = ''): Maybe
     {
         if ($name === '') {
@@ -61,11 +64,13 @@ public static function maybe(string $name, string $value = ''): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function name(): string
     {
         return $this->name;
     }
 
+    #[\NoDiscard]
     public function value(): string
     {
         return $this->value;

src/Document.php

@@ -41,6 +41,7 @@ private function __construct(
      * @param Maybe<Encoding> $encoding
      * @param Sequence<Node|Element|Custom> $children
      */
+    #[\NoDiscard]
     public static function of(
         Version $version,
         Maybe $type,
@@ -50,6 +51,7 @@ public static function of(
         return new self($version, $type, $encoding, $children ?? Sequence::of());
     }
 
+    #[\NoDiscard]
     public function version(): Version
     {
         return $this->version;
@@ -58,6 +60,7 @@ public function version(): Version
     /**
      * @return Maybe<Type>
      */
+    #[\NoDiscard]
     public function type(): Maybe
     {
         return $this->type;
@@ -66,6 +69,7 @@ public function type(): Maybe
     /**
      * @return Sequence<Node|Element|Custom>
      */
+    #[\NoDiscard]
     public function children(): Sequence
     {
         return $this->children;
@@ -74,6 +78,7 @@ public function children(): Sequence
     /**
      * @param callable(Node|Element|Custom): bool $filter
      */
+    #[\NoDiscard]
     public function filterChild(callable $filter): self
     {
         return new self(
@@ -87,6 +92,7 @@ public function filterChild(callable $filter): self
     /**
      * @param callable(Node|Element|Custom): (Node|Element|Custom) $map
      */
+    #[\NoDiscard]
     public function mapChild(callable $map): self
     {
         return new self(
@@ -97,6 +103,7 @@ public function mapChild(callable $map): self
         );
     }
 
+    #[\NoDiscard]
     public function prependChild(Node|Element|Custom $child): self
     {
         $document = clone $this;
@@ -105,6 +112,7 @@ public function prependChild(Node|Element|Custom $child): self
         return $document;
     }
 
+    #[\NoDiscard]
     public function appendChild(Node|Element|Custom $child): self
     {
         $document = clone $this;
@@ -116,11 +124,13 @@ public function appendChild(Node|Element|Custom $child): self
     /**
      * @return Maybe<Encoding>
      */
+    #[\NoDiscard]
     public function encoding(): Maybe
     {
         return $this->encoding;
     }
 
+    #[\NoDiscard]
     public function asContent(Format $format = Format::pretty): Content
     {
         $writer = new \XMLWriter;

src/Document/Encoding.php

@@ -18,6 +18,7 @@ enum Encoding
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function of(string $value): Maybe
     {
         return Maybe::of(match ($value) {
@@ -30,6 +31,7 @@ public static function of(string $value): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function toString(): string
     {
         // @see https://www.iana.org/assignments/character-sets/character-sets.xml

src/Document/Type.php

@@ -28,6 +28,7 @@ private function __construct(
      *
      * @throws DomainException If the name is empty
      */
+    #[\NoDiscard]
     public static function of(
         string $name,
         string $publicId = '',
@@ -44,6 +45,7 @@ public static function of(
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(
         string $name,
         string $publicId = '',
@@ -60,21 +62,25 @@ public static function maybe(
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function name(): string
     {
         return $this->name;
     }
 
+    #[\NoDiscard]
     public function publicId(): string
     {
         return $this->publicId;
     }
 
+    #[\NoDiscard]
     public function systemId(): string
     {
         return $this->systemId;
     }
 
+    #[\NoDiscard]
     public function toString(): string
     {
         return \sprintf(

src/Document/Version.php

@@ -29,6 +29,7 @@ private function __construct(
      *
      * @throws DomainException
      */
+    #[\NoDiscard]
     public static function of(int $major, int $minor = 0): self
     {
         return self::maybe($major, $minor)->match(
@@ -42,6 +43,7 @@ public static function of(int $major, int $minor = 0): self
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(int $major, int $minor = 0): Maybe
     {
         $major = Maybe::just($major)->filter(static fn($int) => $int >= 0);
@@ -55,6 +57,7 @@ public static function maybe(int $major, int $minor = 0): Maybe
     /**
      * @return int<0, max>
      */
+    #[\NoDiscard]
     public function major(): int
     {
         return $this->major;
@@ -63,11 +66,13 @@ public function major(): int
     /**
      * @return int<0, max>
      */
+    #[\NoDiscard]
     public function minor(): int
     {
         return $this->minor;
     }
 
+    #[\NoDiscard]
     public function toString(): string
     {
         return $this->major.'.'.$this->minor;

src/Element.php

@@ -38,6 +38,7 @@ private function __construct(
      * @param Sequence<Attribute>|null $attributes
      * @param Sequence<Node|self|Custom>|null $children
      */
+    #[\NoDiscard]
     public static function of(
         Name $name,
         ?Sequence $attributes = null,
@@ -61,6 +62,7 @@ public static function of(
      *
      * @param Sequence<Attribute>|null $attributes
      */
+    #[\NoDiscard]
     public static function selfClosing(
         Name $name,
         ?Sequence $attributes = null,
@@ -75,6 +77,7 @@ public static function selfClosing(
         );
     }
 
+    #[\NoDiscard]
     public function name(): Name
     {
         return $this->name;
@@ -83,6 +86,7 @@ public function name(): Name
     /**
      * @return Sequence<Attribute>
      */
+    #[\NoDiscard]
     public function attributes(): Sequence
     {
         return $this->attributes;
@@ -93,6 +97,7 @@ public function attributes(): Sequence
      *
      * @return Maybe<Attribute>
      */
+    #[\NoDiscard]
     public function attribute(string $name): Maybe
     {
         return $this->attributes->find(
@@ -103,6 +108,7 @@ public function attribute(string $name): Maybe
     /**
      * @param non-empty-string $name
      */
+    #[\NoDiscard]
     public function removeAttribute(string $name): self
     {
         return new self(
@@ -115,6 +121,7 @@ public function removeAttribute(string $name): self
         );
     }
 
+    #[\NoDiscard]
     public function addAttribute(Attribute $attribute): self
     {
         return new self(
@@ -131,6 +138,7 @@ public function addAttribute(Attribute $attribute): self
     /**
      * @return Sequence<Node|self|Custom>
      */
+    #[\NoDiscard]
     public function children(): Sequence
     {
         return $this->children;
@@ -139,6 +147,7 @@ public function children(): Sequence
     /**
      * @param callable(Node|self|Custom): bool $filter
      */
+    #[\NoDiscard]
     public function filterChild(callable $filter): self
     {
         if ($this->selfClosing) {
@@ -156,6 +165,7 @@ public function filterChild(callable $filter): self
     /**
      * @param callable(Node|self|Custom): (Node|self|Custom) $map
      */
+    #[\NoDiscard]
     public function mapChild(callable $map): self
     {
         if ($this->selfClosing) {
@@ -170,6 +180,7 @@ public function mapChild(callable $map): self
         );
     }
 
+    #[\NoDiscard]
     public function prependChild(Node|self|Custom $child): self
     {
         if ($this->selfClosing) {
@@ -184,6 +195,7 @@ public function prependChild(Node|self|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function appendChild(Node|self|Custom $child): self
     {
         if ($this->selfClosing) {
@@ -198,6 +210,7 @@ public function appendChild(Node|self|Custom $child): self
         );
     }
 
+    #[\NoDiscard]
     public function asContent(Format $format = Format::pretty): Content
     {
         $writer = new \XMLWriter;

src/Element/Custom.php

@@ -10,5 +10,6 @@
  */
 interface Custom
 {
+    #[\NoDiscard]
     public function normalize(): Element;
 }

src/Element/Name.php

@@ -25,6 +25,7 @@ private function __construct(
      *
      * @param non-empty-string $value
      */
+    #[\NoDiscard]
     public static function of(string $value): self
     {
         return new self(null, $value);
@@ -36,6 +37,7 @@ public static function of(string $value): self
      * @param non-empty-string $namespace
      * @param non-empty-string $value
      */
+    #[\NoDiscard]
     public static function namespaced(string $namespace, string $value): self
     {
         return new self($namespace, $value);
@@ -46,6 +48,7 @@ public static function namespaced(string $namespace, string $value): self
      *
      * @return Maybe<self>
      */
+    #[\NoDiscard]
     public static function maybe(string $value): Maybe
     {
         /** @var Maybe<self> */
@@ -58,6 +61,7 @@ public static function maybe(string $value): Maybe
     /**
      * @return non-empty-string
      */
+    #[\NoDiscard]
     public function toString(): string
     {
         if ($this->namespace !== null) {