Add support for skipping lines

Closes GH-9.
Closes GH-14.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>

index.js

@@ -33,7 +33,8 @@ var examples = [
 // Expressions.
 var expressionLog = /(console\.log\()(.+)(\);?)/g
 var expressionRequire = /(require\()(.+)(\);?)/g
-var expressionComment = /^(\s*)(\/\/)(\s*)(.+)/
+var expressionComment = /^(?:\s*)(?:\/\/)(?:\s*)(.+)/
+var expressionIgnore = /^remark-usage-ignore-next(?:(?:\s+)(\d+))?/
 
 // Constants.
 var defaultHeading = 'usage'
@@ -252,6 +253,11 @@ function runFactory(options) {
 // `console.log` calls, and resolves the main `require` call.
 function script(source, options) {
   var tokens
+  var lines
+  var index
+  var length
+  var line
+  var match
 
   // Make sure the require to the main module is shown as if it was a require
   // from `./node_modules`.
@@ -263,7 +269,27 @@ function script(source, options) {
   // Transform comments into markdown:
   tokens = []
 
-  source.split('\n').forEach(each)
+  lines = source.split('\n')
+  index = -1
+  length = lines.length
+
+  while (++index < length) {
+    line = lines[index]
+    match = line.match(expressionComment)
+
+    if (match) {
+      line = match[1]
+      match = line.match(expressionIgnore)
+
+      if (match) {
+        index += (match[1] !== undefined && parseInt(match[1], 10)) || 1
+      } else {
+        tokens.push({type: 'markdown', value: line})
+      }
+    } else {
+      tokens.push({type: 'javascript', value: line})
+    }
+  }
 
   return tokens
 
@@ -283,15 +309,6 @@ function script(source, options) {
 
     return $0
   }
-
-  function each(line) {
-    var match = line.match(expressionComment)
-
-    tokens.push({
-      type: match ? 'markdown' : 'javascript',
-      value: match ? match[4] : line
-    })
-  }
 }
 
 // Preprocess `value` to add IDs to `console.log` invocations.

readme.md

@@ -90,6 +90,20 @@ It’s easiest to check out and compare [`example.js`][example-js] with the abov
 *   Don’t do weird things.
     This is mostly regexes
 
+You can ignore lines like so:
+
+```js
+// remark-usage-ignore-next
+var two = sum(1, 1)
+
+// remark-usage-ignore-next 3
+function sum(a, b) {
+  return a + b
+}
+```
+
+…if no `skip` is given, 1 line is skipped.
+
 ##### `options`
 
 ###### `options.cwd`

test/fixtures/ignore-lines/example.js

@@ -0,0 +1,16 @@
+// Require `pi`:
+var pi = require('./index.js')
+
+// remark-usage-not-an-ignore 1
+var one = 1
+
+// remark-usage-ignore-next
+var two = sum(1, 1)
+
+// remark-usage-ignore-next 3
+function sum(a, b) {
+  return a + b
+}
+
+// Logs:
+console.log('text', pi)

test/fixtures/ignore-lines/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = Math.PI.toString().slice(0, 6);

test/fixtures/ignore-lines/output.md

@@ -0,0 +1,21 @@
+# PI
+
+## Usage
+
+Require `pi`:
+
+```javascript
+var pi = require('pi')
+```
+
+remark-usage-not-an-ignore 1
+
+```javascript
+var one = 1
+```
+
+Logs:
+
+```text
+3.1415
+```

test/fixtures/ignore-lines/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "pi"
+}

test/fixtures/ignore-lines/readme.md

@@ -0,0 +1,3 @@
+# PI
+
+## Usage