Introduce the nested() XML Reader matcher

docs/reader.md

@@ -304,6 +304,66 @@ use \VeeWee\Xml\Reader\Matcher;
 Matcher\namespaced_element('https://some', 'item');
 ```
 
+#### nested
+
+Provide nested matchers that represents parts of an XML tree.
+Every provided matcher acts as a breakpoint for the next matcher, making it composable with the exact XML tree [sequence](#sequence) matcher as well.
+
+Given:
+
+```xml
+<root>
+ <users>
+ <user locale="nl">Jos</user>
+ <user>Bos</user>
+ <user>Mos</user> 
+ </users>
+</root>
+```
+
+This matcher will grab the `user` element with `locale="nl"`
+
+```php
+use \VeeWee\Xml\Reader\Matcher;
+
+Matcher\nested(
+ // Breakpoint 1: <root />
+ Matcher\document_element(),
+ // Breakpoint 2: <user locale="nl">Jos</user>
+ // Searches for all elements that matches `<user />` and attribute `locale="nl"` in the `<root />` document.
+ // Note that you can skip matching on `<users />` here : it's not an exact matcher
+ Matcher\all( 
+ Matcher\element_name('user'),
+ Matcher\attribute_value('locale', 'nl')
+ )
+);
+```
+
+Since every match will create a breakpoint in the `NodeSequence`, you can combine it with the sequence matcher:
+
+```php
+use \VeeWee\Xml\Reader\Matcher;
+
+Matcher\nested(
+ // Breakpoint 1: <root />
+ Matcher\document_element(),
+ // Breakpoint 2: <user />
+ // The nested matcher will provide the NodeSequence starting from the element after previous match.
+ // The sequence will basically receive: 'users > user'
+ Matcher\sequence( 
+ // Level 0: The element inside <root /> at level 0 must exactly match <users /> 
+ Matcher\element_name('users'),
+ // Level 1: The element inside <root /> at level 1 must exactly match <user />
+ Matcher\element_name('user'),
+ ),
+ // Breakpoint 3: <email />
+ // After matching a sequence, you can still continue matching deeper or adding even more sequences:
+ Matcher\element_name('email')
+);
+```
+
+If you want every level of the XML to match exactly, you might use the [sequence](#sequence) matcher instead.
+
 #### not
 
 Inverses a matcher's result.
@@ -318,8 +378,9 @@ Matcher\not(
 
 #### sequence
 
-Provide a sequence of matchers that represents the XML tree.
-Only the items that are described by the sequence will match.
+Provide a sequence of matchers that represents the exact XML tree.
+Every provided matcher step must result in an exact match with the matcher on the same index.
+Only the items that are described by the sequence will match:
 
 Given:
 
@@ -352,6 +413,8 @@ Matcher\sequence(
 );
 ```
 
+If you don't want every level of XML to match exactly, you might use the [nested](#nested) matcher instead.
+
 
 #### Writing your own matcher
 

src/Xml/Reader/Matcher/nested.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace VeeWee\Xml\Reader\Matcher;
+
+use Closure;
+use VeeWee\Xml\Reader\Node\NodeSequence;
+use function array_shift;
+
+/**
+ * A nested matcher can be used to match parts of an XML path in order to detect node you are interested in.
+ * Every match will create some kind of breakpoint of which the next matcher will start.
+ * This makes it possible to combine it with sequences.
+ * Between every matcher, there might be multiple nodes in between.
+ *
+ * ```php
+ * nested(
+ * document_element(),
+ * sequence(element_name('users'), element_name('user')),
+ * element_name('email')
+ * );
+ * ```
+ *
+ * @param non-empty-list<callable(NodeSequence): bool> $matchers
+ *
+ * @return \Closure(NodeSequence): bool
+ */
+function nested(callable ... $matchers): Closure
+{
+ return static function (NodeSequence $sequence) use ($matchers) : bool {
+ $lastMatchedAtIndex = -1;
+ $currentMatcher = array_shift($matchers);
+ if (!$currentMatcher) {
+ return false;
+ }
+
+ $stepCount = $sequence->count();
+ foreach ($sequence->replay() as $index => $step) {
+ // Slice the step NodeSequence based on previous "match" breakpoint
+ // and see if it matches on current matcher:
+ $step = $step->slice($lastMatchedAtIndex + 1);
+ if (!$currentMatcher($step)) {
+ continue;
+ }
+
+ // If there was a match, select the next matcher and store the last matched NodeSequence index.
+ $currentMatcher = array_shift($matchers);
+ $lastMatchedAtIndex = $index;
+
+ // If the list of matchers is empty
+ // The function will return true if the element is the last step in the complete sequence.
+ // Otherwise, the nested match has an even deeper element on which we don't wish to match.
+ if (!$currentMatcher) {
+ $isLastStep = $index === $stepCount - 1;
+
+ return $isLastStep;
+ }
+ }
+
+ return false;
+ };
+}

src/Xml/Reader/Matcher/not.php

@@ -8,7 +8,7 @@
 use VeeWee\Xml\Reader\Node\NodeSequence;
 
 /**
- * @param callable(NodeSequence) $matcher
+ * @param callable(NodeSequence): bool $matcher
  *
  * @return \Closure(NodeSequence): bool
  */

src/Xml/Reader/Matcher/sequence.php

@@ -22,15 +22,12 @@
 function sequence(callable ... $matcherSequence): Closure
 {
  return static function (NodeSequence $sequence) use ($matcherSequence) : bool {
- $nodeSequence = $sequence->sequence();
- if (count($matcherSequence) !== count($nodeSequence)) {
+ if (count($matcherSequence) !== $sequence->count()) {
  return false;
  }
 
- $currentSequence = new NodeSequence();
- foreach ($nodeSequence as $i => $node) {
- $currentSequence = $currentSequence->append($node);
- $matcher = $matcherSequence[$i];
+ foreach ($sequence->replay() as $index => $currentSequence) {
+ $matcher = $matcherSequence[$index];
  if (!$matcher($currentSequence)) {
  return false;
  }

src/Xml/Reader/Node/NodeSequence.php

@@ -4,10 +4,13 @@
 
 namespace VeeWee\Xml\Reader\Node;
 
+use Countable;
+use Generator;
 use InvalidArgumentException;
 use Webmozart\Assert\Assert;
+use function Psl\Vec\slice;
 
-final class NodeSequence
+final class NodeSequence implements Countable
 {
  /**
  * @var list<ElementNode>
@@ -64,6 +67,34 @@ public function sequence(): array
  return $this->elementNodes;
  }
 
+ public function count(): int
+ {
+ return \count($this->elementNodes);
+ }
+
+ /**
+ * @param non-negative-int $start
+ * @param non-negative-int|null $length
+ */
+ public function slice(int $start, ?int $length = null): self
+ {
+ return new self(...slice($this->elementNodes, $start, $length));
+ }
+
+ /**
+ * Replays every step in the sequence
+ *
+ * @return Generator<non-negative-int, NodeSequence, mixed, void>
+ */
+ public function replay(): Generator
+ {
+ $step = new self();
+ foreach ($this->elementNodes as $index => $node) {
+ $step = $step->append($node);
+ yield $index => $step;
+ }
+ }
+
  /**
  * @throws InvalidArgumentException
  */

src/bootstrap.php

@@ -136,6 +136,7 @@
 require_once __DIR__.'/Xml/Reader/Matcher/namespaced_attribute.php';
 require_once __DIR__.'/Xml/Reader/Matcher/namespaced_attribute_value.php';
 require_once __DIR__.'/Xml/Reader/Matcher/namespaced_element.php';
+require_once __DIR__.'/Xml/Reader/Matcher/nested.php';
 require_once __DIR__.'/Xml/Reader/Matcher/node_attribute.php';
 require_once __DIR__.'/Xml/Reader/Matcher/node_name.php';
 require_once __DIR__.'/Xml/Reader/Matcher/not.php';