*/ final class NodeList implements Countable, IteratorAggregate { /** * @var list */ private array $nodes; /** * @no-named-arguments * @param list $nodes */ public function __construct(...$nodes) { $this->nodes = $nodes; } /** * @template X of DOMNode * @return self * * @psalm-suppress InvalidReturnType, InvalidReturnStatement - It is empty alright! */ public static function empty(): self { return new self(); } /** * @template X of DOMNode * @param DOMNodeList $list * @return NodeList */ public static function fromDOMNodeList(DOMNodeList $list): self { return new self(...values($list->getIterator())); } /** * @template X of DOMNode * @param class-string $type * @return NodeList * @throws InvalidArgumentException */ public static function typed(string $type, iterable $nodes): self { Assert::allIsInstanceOf($nodes, $type); return new self(...values($nodes)); } /** * @return Generator */ public function getIterator(): Traversable { yield from $this->nodes; } /** * @return T|null */ public function item(int $index) { return $this->nodes[$index] ?? null; } /** * @throws InvalidArgumentException * @return T */ public function expectItem(int $index, string $message = '') { Assert::notNull($item = $this->item($index), format($message ?: 'No item found at index %s', $index)); return $item; } public function count(): int { return count($this->nodes); } /** * @template R * @param callable(T): R $mapper * * @return list */ public function map(callable $mapper): array { return map($this->nodes, $mapper(...)); } /** * @param callable(T): void $mapper */ public function forEach(callable $mapper): void { foreach ($this->nodes as $node) { $mapper($node); } } /** * @template X of DOMNode * @param callable(T): iterable $mapper * * @return NodeList */ public function detect(callable $mapper): self { return new self( ...flat_map( $this->nodes, $mapper(...) ) ); } /** * @param callable(T): bool $predicate * @return NodeList */ public function filter(callable $predicate): self { return new self(...filter($this->nodes, $predicate(...))); } /** * @return NodeList */ public function eq(int $index): self { if (!array_key_exists($index, $this->nodes)) { return self::empty(); } return new self($this->nodes[$index]); } /** * @template R * @param callable(R, T): R $reducer * @param R $initial * @return R */ public function reduce(callable $reducer, mixed $initial): mixed { return reduce($this->nodes, $reducer(...), $initial); } /** * @param list $configurators * @throws RuntimeException * @return NodeList */ public function query(string $xpath, callable ... $configurators): self { return $this->detect( /** * @param T $node * @return NodeList */ static fn (DOMNode $node): NodeList => Xpath::fromUnsafeNode($node, ...$configurators)->query($xpath, $node) ); } /** * @template X * @param list $configurators * @param TypeInterface $type * @return list */ public function evaluate(string $expression, TypeInterface $type, callable ... $configurators): array { return $this->map( static fn (DOMNode $node): mixed => Xpath::fromUnsafeNode($node, ...$configurators)->evaluate($expression, $type, $node) ); } /** * @return T|null */ public function first() { return $this->item(0); } /** * @throws InvalidArgumentException * @return T */ public function expectFirst(string $message = '') { return $this->expectItem(0, $message); } /** * @throws InvalidArgumentException * @return T */ public function expectSingle(string $message = '') { Assert::true( $this->count() === 1, format($message ?: 'Expected to find exactly one node. Got %s', count($this)) ); return $this->expectItem(0); } /** * @return T|null */ public function last() { return $this->item($this->count() - 1); } /** * @throws InvalidArgumentException * @return T */ public function expectLast(string $message = '') { return $this->expectItem($this->count() - 1, $message); } /** * @return NodeList */ public function siblings(): self { return $this->detect( /** * @return iterable */ static fn (DOMNode $node): NodeList => siblings($node) ); } /** * @return NodeList */ public function ancestors(): self { return $this->detect( /** * @return iterable */ static fn (DOMNode $node): NodeList => ancestors($node) ); } /** * @return NodeList */ public function children(): self { return $this->detect( /** * @return iterable */ static fn (DOMNode $node): NodeList => children($node) ); } /** * @template X of DOMNode * @param class-string $type * @return NodeList * @throws InvalidArgumentException */ public function expectAllOfType(string $type): self { return self::typed($type, $this); } /** * @param callable(T, T): int $sorter * * @return NodeList */ public function sort(callable $sorter): self { return new self(...sort($this->nodes, $sorter(...))); } }