Skip to content

Commit ea41987

Browse files
committed
Readme updates
1 parent 0396ff3 commit ea41987

File tree

1 file changed

+24
-9
lines changed

1 file changed

+24
-9
lines changed

README.md

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# regex-recursion
1+
# regex-recursion ♾️
22

33
[![npm version][npm-version-src]][npm-version-href]
44
[![npm downloads][npm-downloads-src]][npm-downloads-href]
@@ -12,12 +12,17 @@ This is an official plugin for [Regex+](https://github.com/slevithan/regex) that
1212
Recursive matching is added to a regex via one of the following (the recursion depth limit is provided in place of *`N`*):
1313

1414
- `(?R=N)` — Recursively match the entire regex at this position.
15-
- `\g<name&R=N>` or `\g<number&R=N>` — Recursively match the contents of the group referenced by name or number at this position.
16-
- The `\g` subroutine must be *within* the referenced group.
15+
- `\g<name&R=N>` or `\g<number&R=N>` — Recursively match the contents of the group referenced by name or number at this position. The `\g` subroutine must be *within* the referenced group.
1716

18-
Multiple uses of recursion within the same pattern are allowed if they are non-overlapping. Named captures and backreferences are supported within recursion, and are independent per depth level. So e.g. `groups.name` on a match object is the value captured by group `name` at the top level of the recursion stack.
17+
Multiple uses of recursion within the same pattern are allowed if they are non-overlapping. Named captures and backreferences are supported within recursion, and are independent per depth level. So e.g. `match.groups.name` is the value captured by group `name` at the top level of the recursion stack.
1918

20-
## Install and use
19+
## 📜 Contents
20+
21+
- [Install and use](#️-install-and-use)
22+
- [Examples](#-examples)
23+
- [Direct use, without Regex+](#️-direct-use-without-regex)
24+
25+
## 🕹️ Install and use
2126

2227
```sh
2328
npm install regex regex-recursion
@@ -58,7 +63,7 @@ const re = regex({plugins: [recursion]})`…`;
5863
```
5964
</details>
6065

61-
## Examples
66+
## 🪧 Examples
6267

6368
### Match an equal number of two different subpatterns
6469

@@ -100,7 +105,7 @@ const parens = regex({flags: 'g', plugins: [recursion]})`
100105
] */
101106
```
102107

103-
Following is an alternative that matches the same strings, but adds a nested quantifier. It then uses an atomic group to prevent this nested quantifier from creating the potential for [catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html). Since the example above doesn't need a nested quantifier, this is not an improvement but merely an alternative that shows how to deal with the general problem of nested quantifiers with multiple ways to divide matches of the same strings.
108+
Following is an alternative that matches the same strings, but adds a nested quantifier. It then uses an atomic group to prevent the nested quantifier from creating the potential for [catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html). Since the example above doesn't *need* a nested quantifier, this isn't an improvement but merely an alternative that shows how to deal with the general problem of nested quantifiers that create multiple ways to divide matches of the same strings.
104109

105110
```js
106111
const parens = regex({flags: 'g', plugins: [recursion]})`
@@ -154,13 +159,13 @@ const palindromeWords = regex({flags: 'gi', plugins: [recursion]})`
154159
// → ['Racecar', 'ABBA']
155160
```
156161

157-
## Direct use, without Regex+
162+
## ✂️ Direct use, without Regex+
158163

159164
```js
160165
import {recursion} from 'regex-recursion';
161166

162167
// Create a pattern that matches balanced parentheses
163-
const pattern = String.raw`\(([^\(\)]|(?R=10))*\)`;
168+
const pattern = String.raw`\(([^\(\)]|(?R=20))*\)`;
164169
const processed = recursion(pattern);
165170

166171
// The processed pattern can be used as a standard RegExp
@@ -169,6 +174,16 @@ re.exec('foo (bar (baz) blah) end')[0];
169174
// → '(bar (baz) blah)'
170175
```
171176

177+
Because the generated pattern is used without Regex+, you can't include extended syntax like insignificant whitespace, atomic groups, possessive quantifiers, or non-recursive subroutines.
178+
179+
## 🏷️ About
180+
181+
regex-recursion was created by [Steven Levithan](https://github.com/slevithan).
182+
183+
If you want to support this project, I'd love your help by contributing improvements, sharing it with others, or [sponsoring](https://github.com/sponsors/slevithan) ongoing development.
184+
185+
© 2024–present. MIT License.
186+
172187
<!-- Badges -->
173188

174189
[npm-version-src]: https://img.shields.io/npm/v/regex-recursion?color=78C372

0 commit comments

Comments
 (0)