Add support for ignoring final definitions in a section

Related to remarkjs/remark-license#7.

Author: wooorm

index.js

@@ -1,31 +1,36 @@
 'use strict';
 
-/* Dependencies. */
 var toString = require('mdast-util-to-string');
 
-/* Expose. */
 module.exports = headingRange;
 
-/* Methods. */
 var splice = [].splice;
 
-/* Search `node` for `heading` and invoke `callback`. */
-function headingRange(node, heading, callback) {
-  var test = heading;
+/* Search `node` with `options` and invoke `callback`. */
+function headingRange(node, options, callback) {
+  var test = options;
+  var ignoreFinalDefinitions = false;
+
+  /* Object, not regex. */
+  if (test && typeof test === 'object' && !('exec' in test)) {
+    ignoreFinalDefinitions = test.ignoreFinalDefinitions === true;
+    test = test.test;
+  }
 
   if (typeof test === 'string') {
     test = toExpression(test);
   }
 
-  if ('test' in test) {
+  /* Regex */
+  if ('exec' in test) {
     test = wrapExpression(test);
   }
 
-  search(node, test, callback);
+  search(node, test, ignoreFinalDefinitions, callback);
 }
 
 /* Search a node for heading range. */
-function search(root, test, callback) {
+function search(root, test, skip, callback) {
   var index = -1;
   var children = root.children;
   var length = children.length;
@@ -39,20 +44,32 @@ function search(root, test, callback) {
   while (++index < length) {
     child = children[index];
 
-    if (isClosingHeading(child, depth)) {
+    if (closing(child, depth)) {
       end = index;
       break;
     }
 
-    if (isOpeningHeading(child, depth, test)) {
+    if (opening(child, depth, test)) {
       start = index;
       depth = child.depth;
     }
   }
 
   if (start !== null) {
     if (end === null) {
-      end = length + 1;
+      end = length;
+    }
+
+    if (skip) {
+      while (end > start) {
+        child = children[end - 1];
+
+        if (!definition(child)) {
+          break;
+        }
+
+        end--;
+      }
     }
 
     nodes = callback(
@@ -62,7 +79,7 @@ function search(root, test, callback) {
       {
         parent: root,
         start: start,
-        end: end in children ? end : null
+        end: children[end] ? end : null
       }
     );
 
@@ -101,16 +118,20 @@ function wrapExpression(expression) {
 }
 
 /* Check if `node` is a heading. */
-function isHeading(node) {
+function heading(node) {
   return node && node.type === 'heading';
 }
 
 /* Check if `node` is the main heading. */
-function isOpeningHeading(node, depth, test) {
-  return depth === null && isHeading(node) && test(toString(node), node);
+function opening(node, depth, test) {
+  return depth === null && heading(node) && test(toString(node), node);
 }
 
 /* Check if `node` is the next heading. */
-function isClosingHeading(node, depth) {
-  return depth && isHeading(node) && node.depth <= depth;
+function closing(node, depth) {
+  return depth && heading(node) && node.depth <= depth;
+}
+
+function definition(node) {
+  return node.type === 'definition' || node.type === 'footnoteDefinition';
 }

readme.md

@@ -63,33 +63,44 @@ Qux.
 
 ## API
 
-### `heading(node, test, onrun)`
+### `heading(tree, test|options, onrun)`
 
-Transform part of a document without affecting other parts, by changing
-a section: a heading which passes `test`, until the next heading of the
-same or lower depth, or the end of the document.
+Search `tree` ([`Node`][node]) and transform a section without affecting other
+parts with `onrun` ([`Function`][onrun]).
+A Section is a heading that passes `test`, until the next heading of the same
+or lower depth, or the end of the document.  If `ignoreFinalDefinitions: true`,
+final definitions “in” the section are excluded.
 
-###### Parameters
+###### `options`
+
+*   `test` (`string`, `RegExp`, [`Function`][test])
+    — Heading to look for.
+    When `string`, wrapped in `new RegExp('^(' + value + ')$', 'i')`;
+    when `RegExp`, wrapped in `function (value) {expression.test(value)}`
+*   `ignoreFinalDefinitions` (`boolean`, default: `false`)
+    — Ignore final definitions otherwise in the section
+
+#### `function test(value, node)`
+
+Function invoked for each heading with its content (`string`) and `node`
+itself ([`Heading`][heading]) to check if it’s the one to look for.
 
-*   `node` ([`Node`][node]) — Node to search
-*   `test` (`string`, `RegExp`, `function(string, Node): boolean`)
-    — Heading to look for.  When `string`, wrapped in
-    `new RegExp('^(' + value + ')$', 'i')`;  when `RegExp`, wrapped
-    in `function (value) {expression.test(value)}`
-*   `onrun` ([`Function`][onrun])
+###### Returns
+
+`Boolean?`, `true` if this is the heading to use.
 
 #### `function onrun(start, nodes, end?, scope)`
 
 Callback invoked when a range is found.
 
 ###### Parameters
 
-*   `start` (`Heading`) — Start of range
-*   `nodes` (`Array.<Node>`) — Nodes between `start` and `end`
-*   `end` (`Heading?`) — End of range, if any
+*   `start` ([`Heading`][heading]) — Start of range
+*   `nodes` ([`Array.<Node>`][node]) — Nodes between `start` and `end`
+*   `end` ([`Node?`][node]) — End of range, if any
 *   `scope` (`Object`):
 
-    *   `parent` (`Node`) — Parent of the range
+    *   `parent` ([`Node`][node]) — Parent of the range
     *   `start` (`number`) — Index of `start` in `parent`
     *   `end` (`number?`) — Index of `end` in `parent`
 
@@ -122,3 +133,7 @@ Callback invoked when a range is found.
 [node]: https://github.com/syntax-tree/unist#node
 
 [onrun]: #function-onrunstart-nodes-end-scope
+
+[heading]: https://github.com/syntax-tree/mdast#heading
+
+[test]: #function-testvalue-node

test.js

@@ -5,7 +5,7 @@ var remark = require('remark');
 var heading = require('./');
 
 test('mdast-util-heading-range()', function (t) {
-  t.plan(43);
+  t.plan(55);
 
   t.equal(typeof heading, 'function', 'should be a function');
 
@@ -320,19 +320,102 @@ test('mdast-util-heading-range()', function (t) {
       ''
     ].join('\n'), 'should not insert an empty `end`');
   });
+
+  t.equal(
+    process(t, [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      'Bar',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      '',
+      '# Fo',
+      ''
+    ].join('\n'), {test: 'foo', ignoreFinalDefinitions: true}),
+    [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      '',
+      '# Fo',
+      ''
+    ].join('\n'),
+    'ignoreFinalDefinitions: should exclude definitions with an end heading'
+  );
+
+  t.equal(
+    process(t, [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      '',
+      '# Fo',
+      ''
+    ].join('\n'), {test: 'foo', ignoreFinalDefinitions: true}),
+    [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      '',
+      '# Fo',
+      ''
+    ].join('\n'),
+    'ignoreFinalDefinitions: should exclude only definitions'
+  );
+
+  t.equal(
+    process(t, [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      'Bar',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      ''
+    ].join('\n'), {test: 'foo', ignoreFinalDefinitions: true}),
+    [
+      '# Fo',
+      '',
+      '## Foo',
+      '',
+      '[one]: example.com',
+      '',
+      '[two]: example.com',
+      ''
+    ].join('\n'),
+    'ignoreFinalDefinitions: should exclude definitions in the final section'
+  );
 });
 
 /* Shortcut to process. */
-function process(t, value, name) {
+function process(t, value, options) {
   return remark()
     .use(function () {
       return function (node) {
-        heading(node, name, function (start, nodes, end, scope) {
+        heading(node, options, function (start, nodes, end, scope) {
           t.equal(typeof scope.start, 'number');
           t.assert(typeof scope.end === 'number' || scope.end === null);
           t.equal(scope.parent.type, 'root');
-
-          return [start].concat(end ? [end] : []);
+          return [start].concat([end]);
         });
       };
     })