Add elements property to Finder instance

readme.md

@@ -194,19 +194,23 @@ findAndReplaceDOMText(document.getElementById('container'), {
 </div>
 ```
 
-#### The instance
+#### The `Finder` instance
 
-Calling `findAndReplaceDOMText` returns an instance of an internal Finder constructor -- the API on the object is limited, at the moment, to reverting:
+`findAndReplaceDOMText` returns a `Finder` object with the following API:
+
+- **revert()** (`Function`): Rolls back changes to the DOM. **Note:** Reversion will only work if the nodes have not been tampered with after the initial replacement -- if there have been removals, movements or normalisations then the reversion is not guarenteed to work. In this case it's best to retain your own clone of the target node(s) in order to run your own reversion.
+- **elements** (`Array<Array<Element>>`): This is an array of matches, where each match is an array of DOM elements.
+
+Example:
 
 ```js
 var finder = findAndReplaceDOMText(...);
+console.log(finder.elements);
 
 // Later:
 finder.revert();
 ```
 
-**Note:** Reversion will only work if the nodes have not been tampered with after the initial replacement -- if there have been removals, movements or normalisations then the reversion is not guarenteed to work. In this case it's best to retain your own clone of the target node(s) in order to run your own reversion.
-
 ### Contexts
 
 Matching, by default, will occur on all elements and across all element borders. E.g.

src/findAndReplaceDOMText.js

@@ -173,6 +173,8 @@
 
 		this.reverts = [];
 
+		this.elements = [];
+
 		this.matches = this.search();
 
 		if (this.matches.length) {
@@ -436,8 +438,12 @@
 				this.reverts[l]();
 			}
 			this.reverts = [];
+			this.elements = [];
 		},
 
+		// Array of matches, where each match is an array of elements
+		elements: this.elements,
+
 		prepareReplacementString: function(string, portion, match) {
 			var portionMode = this.options.portionMode;
 			if (
@@ -565,6 +571,8 @@
 					newNode.parentNode.replaceChild(node, newNode);
 				});
 
+				this.elements.push([newNode]);
+
 				return newNode;
 
 			} else {
@@ -606,6 +614,8 @@
 					match
 				);
 
+				this.elements.push([firstNode].concat(innerNodes).concat([lastNode]));
+
 				matchStartNode.parentNode.insertBefore(precedingTextNode, matchStartNode);
 				matchStartNode.parentNode.insertBefore(firstNode, matchStartNode);
 				matchStartNode.parentNode.removeChild(matchStartNode);

test/test.js

@@ -392,6 +392,26 @@ test('Across node boundaries', function() {
 	htmlEqual(d.innerHTML, original);
 });
 
+module('Getting matches from the Finder instance');
+
+test('Gets matches', function() {
+	var d = document.createElement('div');
+	d.innerHTML = 'foobar foo<em>bar</em>';
+	var finder = findAndReplaceDOMText(d, {
+		find: /foobar/g,
+		wrap: 'span'
+	});
+
+	equal(finder.elements.length, 2);
+
+	equal(finder.elements[0].length, 1);
+	equal(finder.elements[0][0].innerText, "foobar");
+
+	equal(finder.elements[1].length, 2);
+	equal(finder.elements[1][0].innerText, "foo");
+	equal(finder.elements[1][1].innerText, "bar");
+});
+
 module('Legacy');
 
 test('Deprecated argument signature', function() {