Add match structure object for safer HTML wrapping of strings

README.md

@@ -79,6 +79,37 @@ console.log(matches);
 // [ '<b>a<c>o<n>ing', 'a mighty <b>ear <c>a<n>oe' ]
 ```
 
+Chewbacca: sometimes you don't want to get unsafely wrapped html structures,
+and you'd rather do it yourself later. Prepending and appending strings is
+cool until you use React and don't want XSS. You can tell fuzzy.js to return
+small 'match info' objects to suit your needs better.
+
+```javascript
+var list = ['rey', 'kylo ren', 'finn'];
+var options = { returnMatchInfo: true };
+var results = fuzzy.filter('ren', list, options);
+console.log(results);
+// [ { string:
+//      [ {match: true, char: 'r'},
+//        {match: true, char: 'e'},
+//        {match: false, char: 'y'} ],
+//     score: 4,
+//     index: 0,
+//     original: 'rey' },
+//   { string:
+//      [ {match: false, char: 'k'},
+//        {match: false, char: 'y'},
+//        {match: false, char: 'l'},
+//        {match: false, char: 'o'},
+//        {match: false, char: ' '},
+//        {match: true,  char: 'r'},
+//        {match: true,  char: 'e'},
+//        {match: false, char: 'n'} ],
+//     score: 4,
+//     index: 1,
+//     original: 'kylo ren' } ]
+```
+
 ## Examples
 Check out the html files in the [examples](https://github.com/mattyork/fuzzy/tree/master/examples) directory.
 

lib/fuzzy.js

@@ -34,6 +34,10 @@ fuzzy.test = function(pattern, string) {
 
 // If `pattern` matches `string`, wrap each matching character
 // in `opts.pre` and `opts.post`. If no match, return null
+// If `opts.returnMatchInfo` is true, return an array of objects
+// with boolean match info.
+// `opts.pre` and `opts.post` can be used with `opts.returnMatchInfo`
+// if necessary.
 fuzzy.match = function(pattern, string, opts) {
   opts = opts || {};
   var patternIdx = 0
@@ -45,18 +49,21 @@ fuzzy.match = function(pattern, string, opts) {
     , pre = opts.pre || ''
     // suffix
     , post = opts.post || ''
+    , returnMatchInfo = opts.returnMatchInfo || false
     // String to compare against. This might be a lowercase version of the
     // raw string
     , compareString =  opts.caseSensitive && string || string.toLowerCase()
-    , ch, compareChar;
+    , ch, compareChar, chMatch;
 
   pattern = opts.caseSensitive && pattern || pattern.toLowerCase();
 
   // For each character in the string, either add it to the result
   // or wrap in template if it's the next string in the pattern
   for(var idx = 0; idx < len; idx++) {
+    chMatch = false;
     ch = string[idx];
     if(compareString[idx] === pattern[patternIdx]) {
+      chMatch = true;
       ch = pre + ch + post;
       patternIdx += 1;
 
@@ -66,12 +73,22 @@ fuzzy.match = function(pattern, string, opts) {
       currScore = 0;
     }
     totalScore += currScore;
-    result[result.length] = ch;
+
+    // assemble match info object if requested
+    if(returnMatchInfo) {
+      result[result.length] = {match: chMatch, char: ch};
+    } else {
+      result[result.length] = ch;
+    }
   }
 
-  // return rendered string if we have a match for every char
+  // return rendered string/array if we have a match for every char
   if(patternIdx === pattern.length) {
-    return {rendered: result.join(''), score: totalScore};
+    // join if not returning match info object
+    if(!returnMatchInfo) {
+      result = result.join('');
+    }
+    return {rendered: result, score: totalScore};
   }
 
   return null;

test/fuzzy.test.js

@@ -105,6 +105,24 @@ describe('fuzzy', function(){
       })[0].string;
       expect(rendered).to.eql('c<a>c<b>c');
     });
+    it('should optionally return an object surrounding each character', function(){
+      var fuzzyMatched = fuzzy.filter('a', ['a'], {
+        returnMatchInfo: true
+      })[0].string;
+      expect(fuzzyMatched).to.eql([{match: true, char: 'a'}]);
+
+      fuzzyMatched = fuzzy.filter('a', ['ab'], {
+        returnMatchInfo: true
+      })[0].string;
+      expect(fuzzyMatched).to.eql([{match: true, char: 'a'}, {match: false, char: 'b'}]);
+
+      fuzzyMatched = fuzzy.filter('a', ['ab'], {
+          returnMatchInfo: true
+        , pre: "tah"
+        , post: "zah!"
+      })[0].string;
+      expect(fuzzyMatched).to.eql([{match: true, char: 'tahazah!'}, {match: false, char: 'b'}]);
+    })
     it('should use optional func to get string out of array entry', function() {
       var arr = [{arg: 'hizzahpooslahp'}, {arg: 'arppg'}];
       expect(fuzzy.filter('poop', arr, {