azu / match-index

Get index of each capture.

match-index

Deprecated: use native String.prototype.matchAll() and RegExp Match Indices

Get index of each capture.

• Get index of each capture in a JavaScript regex - Stack Overflow
• tc39/String.prototype.matchAll: ES Proposal, specs, tests, reference implementation, and polyfill/shim for String.prototype.matchAll

Status: Deprecated

indices property cover this library usecase.

• tc39/proposal-regexp-match-indices: ECMAScript RegExp Match Indices
• regexp-match-indices - npm

Why?

You want to match a regex like /(a.)(b)(c.)d/ with "aabccde", and get the following information back:

"aa" at index = 0
"b" at index = 2
"cc" at index = 3

But, it is difficult to write.

match-index provide matchCaptureGroupAll function that easy to get this information!

const text = "aabccde";
const regExp = /(a.)(b)(c.)d/;
const captureGroups = matchCaptureGroupAll(text, regExp);
// array of `MatchCaptureGroup`
assert.equal(captureGroups.length, 3);
const [a, b, c]= captureGroups;
assert.equal(a.text, "aa");
assert.equal(a.index, 0);
assert.equal(b.text, "b");
assert.equal(b.index, 2);
assert.equal(c.text, "cc");
assert.equal(c.index, 3);

Installation

npm install match-index

Usage

match-index provide two functions

matchCaptureGroupAll(text, regExp): MatchCaptureGroup

Retrieves the captured matches when matching a string against a regular expression.

Example of matchCaptureGroupAll()

// get "ABC" and "EFC that are captured by ( and )
const captureGroups = matchCaptureGroupAll("ABC EFG", /(ABC).*?(EFG)/);
// captureGroups is array of MatchAllGroup
/**
 * @typedef {Object} MatchAllGroup
 * @property {Array} all
 * @property {string} input
 * @property {number} index
 * @property {MatchCaptureGroup[]} captureGroups
 */
assert(captureGroups.length, 2);
const [x, y] = captureGroups;
assert.equal(x.text, "ABC");
assert.equal(x.index, 0);
assert.equal(y.text, "EFG");
assert.equal(y.index, 4);

matchCaptureGroupAll use matchAll in internal.

matchAll(text, regExp): MatchAllGroup

Retrieves the matches all when matching a string against a regular expression.

Example of matchAll()

const text = 'test1test2';
const regexp = /t(e)(st(\d?))/g;
const captureGroups = matchAll(text, regexp);
// captureGroups is array of `MatchAllGroup`
/**
 * @typedef {Object} MatchAllGroup
 * @property {Array} all
 * @property {string} input
 * @property {number} index
 * @property {MatchCaptureGroup[]} captureGroups
 */

assert.equal(captureGroups.length, 2);
const [test1, test2] = captureGroups;
assert.equal(test1.index, 0);
assert.equal(test1.input, text);
assert.deepEqual(test1.all, ['test1', 'e', 'st1', '1']);
assert.deepEqual(test1.captureGroups, [
    {
        index: 1,
        text: 'e'
    }, {
        index: 2,
        text: 'st1'
    }, {
        index: -1,// Limitation of capture nest
        text: '1'
    }
]);
assert.equal(test2.index, 5);
assert.equal(test2.input, text);
assert.deepEqual(test2.all, ['test2', 'e', 'st2', '2']);
assert.deepEqual(test2.captureGroups, [
    {
        index: 6,
        text: 'e'
    }, {
        index: 7,
        text: 'st2'
    }, {
        index: -1, // Limitation
        text: '2'
    }
]);

Notes

Limitation ⚠️

matchAll and matchCaptureGroupAll doesn't support nest capture.

e.g.) last captureGroups item's index is wrong result.

(st(\d?)) is nest capture.

const text = 'test1test2';
const regexp = /t(e)(st(\d?))/g;
const captureGroups = matchAll(text, regexp);
// captureGroups is array of `MatchAllGroup`
/**
 * @typedef {Object} MatchAllGroup
 * @property {Array} all
 * @property {string} input
 * @property {number} index
 * @property {MatchCaptureGroup[]} captureGroups
 */

assert.equal(captureGroups.length, 2);
const [test1, test2] = captureGroups;
assert.equal(test1.index, 0);
assert.equal(test1.input, text);
assert.deepEqual(test1.all, ['test1', 'e', 'st1', '1']);
assert.deepEqual(test1.captureGroups, [
    {
        index: 1,
        text: 'e'
    }, {
        index: 2,
        text: 'st1'
    }, {
        index: -1,// Limitation of capture nest
        text: '1'
    }
]);

Welcome to pull request to fix this limitation :)

Tests

npm test

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

License

MIT

match-index's Issues

matchCaptureGroupAll returns wrong matches

const text = 'abc1abc1'
const regexp = /([a-z])*(1)/
const captureGroups = matchCaptureGroupAll(text, regexp)

returns

[ { text: 'c', index: 2 },
  { text: '1', index: 3 },
  { text: 'c', index: 6 },
  { text: '1', index: 7 } ]

which is wrong as there are four groups in the result. Also two of them are associated with the group (1) that has no quantifiers in the regex literal.

matchCaptureGroupAll throws error when a capturing group is undefined

const text = 'abc1abc1'
const regexp = /([a-z])*([a-z])*(1)/
const captureGroups = matchCaptureGroupAll(text, regexp)

throws an error:

/Users/marko/projects/match-index/lib/match-index.js:84
      cursor = index + groups[i].length;
                                 ^

TypeError: Cannot read property 'length' of undefined

which is probably a consequence of the fact that the second group has no match and is therefore undefined.