Implement for...of iterator via Symbol.iterator (#1197)

* Implement for...of iterator via Symbol.iterator

Similar to jQuery: https://github.com/jquery/jquery/blob/1ea092a54b00aa4d902f4e22ada3854d195d4a18/src/core.js#L371-L373

Fixes #1191

* Assert that the iterator ends

#1197 (comment)

lib/cheerio.js

@@ -1,3 +1,4 @@
+/*global Symbol*/
 /*
   Module dependencies
 */
@@ -138,6 +139,11 @@ Cheerio.prototype.toArray = function() {
   return this.get();
 };
 
+// Support for (const element of $(...)) iteration:
+if (typeof Symbol !== 'undefined') {
+  Cheerio.prototype[Symbol.iterator] = Array.prototype[Symbol.iterator];
+}
+
 // Plug in the API
 api.forEach(function(mod) {
   _.extend(Cheerio.prototype, mod);

test/api/traversing.js

@@ -1,3 +1,4 @@
+/*global Symbol*/
 var expect = require('expect.js'),
     cheerio = require('../..'),
     food = require('../fixtures').food,
@@ -680,6 +681,21 @@ describe('$(...)', function() {
     });
   });
 
+  if (typeof Symbol !== 'undefined') {
+    describe('[Symbol.iterator]', function() {
+
+      it('should yield each element', function() {
+        // The equivalent of: for (const element of $('li')) ...
+        var $li = $('li'),
+            iterator = $li[Symbol.iterator]();
+        expect(iterator.next().value.attribs['class']).to.equal('apple');
+        expect(iterator.next().value.attribs['class']).to.equal('orange');
+        expect(iterator.next().value.attribs['class']).to.equal('pear');
+        expect(iterator.next().done).to.equal(true);
+      });
+    });
+  }
+
   describe('.map', function() {
     it('(fn) : should be invoked with the correct arguments and context', function() {
       var $fruits = $('li');