|
| 1 | +# regex-to-strings |
| 2 | + |
| 3 | +[](https://badge.fury.io/js/regex-to-strings) |
| 4 | + |
| 5 | + |
| 6 | +[](https://travis-ci.org/wimpyprogrammer/regex-to-strings) |
| 7 | +[](https://codecov.io/gh/wimpyprogrammer/regex-to-strings) |
| 8 | +[](https://snyk.io/test/github/wimpyprogrammer/regex-to-strings) |
| 9 | + |
| 10 | +Generate strings that match a Regular Expression pattern. Efficiently generate all possible matches, or only the quantity you need. |
| 11 | + |
| 12 | +Have you ever: |
| 13 | + |
| 14 | +- scrutinized a Regular Expression while trying to visualize what it does and doesn't match? |
| 15 | +- crafted a list of strings to test whether a Regular Expression is working as intended? |
| 16 | +- needed to generate filler data like phone numbers, addresses, zip codes, and email addresses? |
| 17 | + |
| 18 | +`regex-to-strings` helps with problems like these! |
| 19 | + |
| 20 | +## <a href="https://www.wimpyprogrammer.com/regex-to-strings/">Demo</a> |
| 21 | + |
| 22 | +## API |
| 23 | + |
| 24 | +### `expand(regExPattern)` |
| 25 | + |
| 26 | +The `regExPattern` parameter supports three formats: |
| 27 | + |
| 28 | +1. A `RegExp` object, like `/[a-z]/i` |
| 29 | +1. A `string` that looks like a `RegExp` object, like `"/[a-z]/i"` |
| 30 | +1. A `string` containing just a Regular Expression pattern, like `"[a-z]"` |
| 31 | + |
| 32 | +The returned object contains two properties: |
| 33 | + |
| 34 | +- `count`: The total number of strings that match `regExPattern` |
| 35 | +- `getIterator()`: A [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) that yields strings matched by `regExPattern` |
| 36 | + |
| 37 | +```js |
| 38 | +import { expand } from 'regex-to-strings'; |
| 39 | + |
| 40 | +const phoneNumberPattern = /((\(555\) ?)|(555-))?\d{3}-\d{4}/; |
| 41 | +const phoneNumberExpander = expand(phoneNumberPattern); |
| 42 | + |
| 43 | +console.log(phoneNumberExpander.count); // 40000000 |
| 44 | + |
| 45 | +for (const phoneNumber of phoneNumberExpander.getIterator()) { |
| 46 | + console.log(phoneNumber); |
| 47 | + // (555)547-4836 |
| 48 | + // 476-2063 |
| 49 | + // 467-2475 |
| 50 | + // (555) 194-2532 |
| 51 | + // (555)403-4986 |
| 52 | + // 555-838-9771 |
| 53 | + // etc. |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +--- |
| 58 | + |
| 59 | +### `count(regExPattern)` |
| 60 | + |
| 61 | +A shortcut to the `count` property of `expand(regExPattern)`. |
| 62 | + |
| 63 | +```js |
| 64 | +import { count } from 'regex-to-strings'; |
| 65 | + |
| 66 | +const numStrings = count(/[a-z]{5}/i); |
| 67 | +console.log(numStrings); // 380204032 |
| 68 | +``` |
| 69 | + |
| 70 | +--- |
| 71 | + |
| 72 | +### `expandN(regExPattern, n)` |
| 73 | + |
| 74 | +A shortcut to take `n` strings from `expand(regExPattern).getIterator()`. |
| 75 | + |
| 76 | +```js |
| 77 | +import { expandN } from 'regex-to-strings'; |
| 78 | + |
| 79 | +const strings = expandN(/\d{3,5}/, 5); |
| 80 | +console.log(strings); // ['84504', '94481', '3971', '69398', '7792'] |
| 81 | +``` |
| 82 | + |
| 83 | +If the Regular Expression matches fewer than `n` strings, the returned array will contain fewer than `n` elements. |
| 84 | + |
| 85 | +```js |
| 86 | +import { expandN } from 'regex-to-strings'; |
| 87 | + |
| 88 | +const strings = expandN(/[abc]/, 100); |
| 89 | +console.log(strings); // ['b', 'a', 'c'] |
| 90 | +``` |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +### `expandAll(regExPattern)` |
| 95 | + |
| 96 | +A shortcut to get all strings from `expand(regExPattern).getIterator()`. |
| 97 | + |
| 98 | +```js |
| 99 | +import { expandAll } from 'regex-to-strings'; |
| 100 | + |
| 101 | +const strings = expandAll(/\d/); |
| 102 | +console.log(strings); // ['6', '5', '0', '2', '7', '9', '4', '3', '1', '8'] |
| 103 | +``` |
| 104 | + |
| 105 | +## Notes |
| 106 | + |
| 107 | +### Supported Regular Expression syntax |
| 108 | + |
| 109 | +`regex-to-strings` uses [`regexp-tree`](https://www.npmjs.com/package/regexp-tree) to parse your Regular Expression, and so the Regular Expression syntax you can use is largely determined by that library. If your pattern is not recognized by `regex-to-strings`, [try parsing it with `regexp-tree`](https://astexplorer.net/#/gist/4ea2b52f0e546af6fb14f9b2f5671c1c/39b55944da3e5782396ffa1fea3ba68d126cd394) to see if the syntax is supported. |
| 110 | + |
| 111 | +`regex-to-strings` also includes [extensive positive **and** negative tests](https://github.com/wimpyprogrammer/regex-to-strings/blob/master/src/pattern.spec.ts) that track which Regular Expression features are supported. |
| 112 | + |
| 113 | +### Regular Expressions with unbounded repetition |
| 114 | + |
| 115 | +Regular Expressions support many techniques for matching an unlimited number of characters. For example, the following patterns will match as many `a`'s as possible: |
| 116 | + |
| 117 | +- `/a*/` |
| 118 | +- `/a+/` |
| 119 | +- `/a{7,}/` |
| 120 | + |
| 121 | +When `regex-to-strings` encounters a repetition with no upper bound, it artificially sets an upper bound of **100**. This is done for many reasons, chiefly so that a simple pattern like `expandAll(/a+/)` will not cause an infinite loop. |
| 122 | + |
| 123 | +This also affects the `count` calculation; `expand(/a+/).count` returns `100` rather than `Infinity`. |
| 124 | + |
| 125 | +### Randomizing the results |
| 126 | + |
| 127 | +`regex-to-strings` goes to great lengths to randomize the generated strings. Otherwise the results would be predictable, uninteresting, and probably unhelpful. |
| 128 | + |
| 129 | +```js |
| 130 | +// How results might appear without randomization |
| 131 | +const strings = expandN(/\d+/, 10); |
| 132 | +console.log(strings); // ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] |
| 133 | +``` |
| 134 | + |
| 135 | +Random selections occur throughout the string generation process to give you a thorough sampling of matching strings. |
| 136 | + |
| 137 | +## Credits |
| 138 | + |
| 139 | +`regex-to-strings` relies heavily on the [`regexp-tree`](https://www.npmjs.com/package/regexp-tree) Regular Expression parser by [Dmitry Soshnikov](https://github.com/DmitrySoshnikov). Thanks! |
0 commit comments