Skip to content

Commit 716eb9f

Browse files
paulmillrpaulmillr
committed
readme bump
1 parent a5851e5 commit 716eb9f

File tree

1 file changed

+90
-97
lines changed

1 file changed

+90
-97
lines changed

‎README.md

+90-97
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,15 @@ See the [changelog](CHANGELOG.md) for details.
2020

2121
Brace patterns make globs more powerful by adding the ability to match specific ranges and sequences of characters.
2222

23-
* **Accurate** - complete support for the [Bash 4.3 Brace Expansion](www.gnu.org/software/bash/) specification (passes all of the Bash braces tests)
24-
* **[fast and performant](#benchmarks)** - Starts fast, runs fast and [scales well](#performance) as patterns increase in complexity.
25-
* **Organized code base** - The parser and compiler are easy to maintain and update when edge cases crop up.
26-
* **Well-tested** - Thousands of test assertions, and passes all of the Bash, minimatch, and [brace-expansion](https://github.com/juliangruber/brace-expansion) unit tests (as of the date this was written).
27-
* **Safer** - You shouldn't have to worry about users defining aggressive or malicious brace patterns that can break your application. Braces takes measures to prevent malicious regex that can be used for DDoS attacks (see [catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html)).
28-
* [Supports lists](#lists) - (aka "sets") `a/{b,c}/d` => `['a/b/d', 'a/c/d']`
29-
* [Supports sequences](#sequences) - (aka "ranges") `{01..03}` => `['01', '02', '03']`
30-
* [Supports steps](#steps) - (aka "increments") `{2..10..2}` => `['2', '4', '6', '8', '10']`
31-
* [Supports escaping](#escaping) - To prevent evaluation of special characters.
23+
- **Accurate** - complete support for the [Bash 4.3 Brace Expansion](www.gnu.org/software/bash/) specification (passes all of the Bash braces tests)
24+
- **[fast and performant](#benchmarks)** - Starts fast, runs fast and [scales well](#performance) as patterns increase in complexity.
25+
- **Organized code base** - The parser and compiler are easy to maintain and update when edge cases crop up.
26+
- **Well-tested** - Thousands of test assertions, and passes all of the Bash, minimatch, and [brace-expansion](https://github.com/juliangruber/brace-expansion) unit tests (as of the date this was written).
27+
- **Safer** - You shouldn't have to worry about users defining aggressive or malicious brace patterns that can break your application. Braces takes measures to prevent malicious regex that can be used for DDoS attacks (see [catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html)).
28+
- [Supports lists](#lists) - (aka "sets") `a/{b,c}/d` => `['a/b/d', 'a/c/d']`
29+
- [Supports sequences](#sequences) - (aka "ranges") `{01..03}` => `['01', '02', '03']`
30+
- [Supports steps](#steps) - (aka "increments") `{2..10..2}` => `['2', '4', '6', '8', '10']`
31+
- [Supports escaping](#escaping) - To prevent evaluation of special characters.
3232

3333
## Usage
3434

@@ -52,9 +52,9 @@ By default, brace patterns are compiled into strings that are optimized for crea
5252
**Compiled**
5353

5454
```js
55-
console.log(braces('a/{x,y,z}/b'));
55+
console.log(braces('a/{x,y,z}/b'));
5656
//=> ['a/(x|y|z)/b']
57-
console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
57+
console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
5858
//=> [ 'a/(0[1-9]|1[0-9]|20)/b', 'a/([1-5])/b' ]
5959
```
6060

@@ -87,13 +87,13 @@ console.log(braces.expand('a/{foo,bar,baz}/*.js'));
8787
Expand ranges of characters (like Bash "sequences"):
8888

8989
```js
90-
console.log(braces.expand('{1..3}')); // ['1', '2', '3']
91-
console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
92-
console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
90+
console.log(braces.expand('{1..3}')); // ['1', '2', '3']
91+
console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
92+
console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
9393
console.log(braces('foo/{a..c}', { expand: true })); // ['foo/a', 'foo/b', 'foo/c']
9494

9595
// supports zero-padded ranges
96-
console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
96+
console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
9797
console.log(braces('a/{001..300}/b')); //=> ['a/(0{2}[1-9]|0[1-9][0-9]|[12][0-9]{2}|300)/b']
9898
```
9999

@@ -183,7 +183,7 @@ console.log(braces.expand('a{b}c'));
183183
**Description**: Limit the length of the input string. Useful when the input string is generated or your application allows users to pass a string, et cetera.
184184

185185
```js
186-
console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error
186+
console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error
187187
```
188188

189189
### options.maxSymbols
@@ -192,10 +192,10 @@ console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error
192192

193193
**Default**: `1024`
194194

195-
**Description**: Limit the count of unique symbols the input string.
195+
**Description**: Limit the count of unique symbols the input string.
196196

197197
```js
198-
console.log(braces('a/{b,c}/d', { maxSymbols: 2 })); //=> throws an error
198+
console.log(braces('a/{b,c}/d', { maxSymbols: 2 })); //=> throws an error
199199
```
200200

201201
### options.expand
@@ -256,7 +256,7 @@ const alpha = braces.expand('x/{a..e}/y', {
256256
transform(value, index) {
257257
// When non-numeric values are passed, "value" is a character code.
258258
return 'foo/' + String.fromCharCode(value) + '-' + index;
259-
}
259+
},
260260
});
261261
console.log(alpha);
262262
//=> [ 'x/foo/a-0/y', 'x/foo/b-1/y', 'x/foo/c-2/y', 'x/foo/d-3/y', 'x/foo/e-4/y' ]
@@ -269,9 +269,9 @@ const numeric = braces.expand('{1..5}', {
269269
transform(value) {
270270
// when numeric values are passed, "value" is a number
271271
return 'foo/' + value * 2;
272-
}
272+
},
273273
});
274-
console.log(numeric);
274+
console.log(numeric);
275275
//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]
276276
```
277277

@@ -293,9 +293,9 @@ The `quantifiers` option tells braces to detect when [regex quantifiers](https:/
293293
const braces = require('braces');
294294
console.log(braces('a/b{1,3}/{x,y,z}'));
295295
//=> [ 'a/b(1|3)/(x|y|z)' ]
296-
console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true}));
296+
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true }));
297297
//=> [ 'a/b{1,3}/(x|y|z)' ]
298-
console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true, expand: true}));
298+
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true, expand: true }));
299299
//=> [ 'a/b{1,3}/x', 'a/b{1,3}/y', 'a/b{1,3}/z' ]
300300
```
301301

@@ -313,8 +313,8 @@ Brace expansion is a type of parameter expansion that was made popular by unix s
313313

314314
In addition to "expansion", braces are also used for matching. In other words:
315315

316-
* [brace expansion](#brace-expansion) is for generating new lists
317-
* [brace matching](#brace-matching) is for filtering existing lists
316+
- [brace expansion](#brace-expansion) is for generating new lists
317+
- [brace matching](#brace-matching) is for filtering existing lists
318318

319319
<details>
320320
<summary><strong>More about brace expansion</strong> (click to expand)</summary>
@@ -394,9 +394,9 @@ Although brace patterns offer a user-friendly way of matching ranges or sets of
394394

395395
**"brace bombs"**
396396

397-
* brace expansion can eat up a huge amount of processing resources
398-
* as brace patterns increase _linearly in size_, the system resources required to expand the pattern increase exponentially
399-
* users can accidentally (or intentially) exhaust your system's resources resulting in the equivalent of a DoS attack (bonus: no programming knowledge is required!)
397+
- brace expansion can eat up a huge amount of processing resources
398+
- as brace patterns increase _linearly in size_, the system resources required to expand the pattern increase exponentially
399+
- users can accidentally (or intentially) exhaust your system's resources resulting in the equivalent of a DoS attack (bonus: no programming knowledge is required!)
400400

401401
For a more detailed explanation with examples, see the [geometric complexity](#geometric-complexity) section.
402402

@@ -418,8 +418,8 @@ For example, the following sets demonstrate quadratic (`O(n^2)`) complexity:
418418
But add an element to a set, and we get a n-fold Cartesian product with `O(n^c)` complexity:
419419

420420
```
421-
{1,2,3}{4,5,6}{7,8,9} => (3X3X3) => 147 148 149 157 158 159 167 168 169 247 248
422-
249 257 258 259 267 268 269 347 348 349 357
421+
{1,2,3}{4,5,6}{7,8,9} => (3X3X3) => 147 148 149 157 158 159 167 168 169 247 248
422+
249 257 258 259 267 268 269 347 348 349 357
423423
358 359 367 368 369
424424
```
425425

@@ -436,9 +436,9 @@ Although these examples are clearly contrived, they demonstrate how brace patter
436436

437437
Interested in learning more about brace expansion?
438438

439-
* [linuxjournal/bash-brace-expansion](http://www.linuxjournal.com/content/bash-brace-expansion)
440-
* [rosettacode/Brace_expansion](https://rosettacode.org/wiki/Brace_expansion)
441-
* [cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
439+
- [linuxjournal/bash-brace-expansion](http://www.linuxjournal.com/content/bash-brace-expansion)
440+
- [rosettacode/Brace_expansion](https://rosettacode.org/wiki/Brace_expansion)
441+
- [cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
442442

443443
</details>
444444

@@ -456,25 +456,25 @@ Instead, convert the pattern into an optimized regular expression. This is easie
456456

457457
Minimatch gets exponentially slower as patterns increase in complexity, braces does not. The following results were generated using `braces()` and `minimatch.braceExpand()`, respectively.
458458

459-
| **Pattern** | **braces** | **[minimatch][]** |
460-
| --- | --- | --- |
461-
| `{1..9007199254740991}`[^1] | `298 B` (5ms 459μs)| N/A (freezes) |
462-
| `{1..1000000000000000}` | `41 B` (1ms 15μs) | N/A (freezes) |
463-
| `{1..100000000000000}` | `40 B` (890μs) | N/A (freezes) |
464-
| `{1..10000000000000}` | `39 B` (2ms 49μs) | N/A (freezes) |
465-
| `{1..1000000000000}` | `38 B` (608μs) | N/A (freezes) |
466-
| `{1..100000000000}` | `37 B` (397μs) | N/A (freezes) |
467-
| `{1..10000000000}` | `35 B` (983μs) | N/A (freezes) |
468-
| `{1..1000000000}` | `34 B` (798μs) | N/A (freezes) |
469-
| `{1..100000000}` | `33 B` (733μs) | N/A (freezes) |
470-
| `{1..10000000}` | `32 B` (5ms 632μs) | `78.89 MB` (16s 388ms 569μs) |
471-
| `{1..1000000}` | `31 B` (1ms 381μs) | `6.89 MB` (1s 496ms 887μs) |
472-
| `{1..100000}` | `30 B` (950μs) | `588.89 kB` (146ms 921μs) |
473-
| `{1..10000}` | `29 B` (1ms 114μs) | `48.89 kB` (14ms 187μs) |
474-
| `{1..1000}` | `28 B` (760μs) | `3.89 kB` (1ms 453μs) |
475-
| `{1..100}` | `22 B` (345μs) | `291 B` (196μs) |
476-
| `{1..10}` | `10 B` (533μs) | `20 B` (37μs) |
477-
| `{1..3}` | `7 B` (190μs) | `5 B` (27μs) |
459+
| **Pattern** | **braces** | **[minimatch][]** |
460+
| --------------------------- | ------------------- | ---------------------------- |
461+
| `{1..9007199254740991}`[^1] | `298 B` (5ms 459μs) | N/A (freezes) |
462+
| `{1..1000000000000000}` | `41 B` (1ms 15μs) | N/A (freezes) |
463+
| `{1..100000000000000}` | `40 B` (890μs) | N/A (freezes) |
464+
| `{1..10000000000000}` | `39 B` (2ms 49μs) | N/A (freezes) |
465+
| `{1..1000000000000}` | `38 B` (608μs) | N/A (freezes) |
466+
| `{1..100000000000}` | `37 B` (397μs) | N/A (freezes) |
467+
| `{1..10000000000}` | `35 B` (983μs) | N/A (freezes) |
468+
| `{1..1000000000}` | `34 B` (798μs) | N/A (freezes) |
469+
| `{1..100000000}` | `33 B` (733μs) | N/A (freezes) |
470+
| `{1..10000000}` | `32 B` (5ms 632μs) | `78.89 MB` (16s 388ms 569μs) |
471+
| `{1..1000000}` | `31 B` (1ms 381μs) | `6.89 MB` (1s 496ms 887μs) |
472+
| `{1..100000}` | `30 B` (950μs) | `588.89 kB` (146ms 921μs) |
473+
| `{1..10000}` | `29 B` (1ms 114μs) | `48.89 kB` (14ms 187μs) |
474+
| `{1..1000}` | `28 B` (760μs) | `3.89 kB` (1ms 453μs) |
475+
| `{1..100}` | `22 B` (345μs) | `291 B` (196μs) |
476+
| `{1..10}` | `10 B` (533μs) | `20 B` (37μs) |
477+
| `{1..3}` | `7 B` (190μs) | `5 B` (27μs) |
478478

479479
### Faster algorithms
480480

@@ -483,7 +483,7 @@ When you need expansion, braces is still much faster.
483483
_(the following results were generated using `braces.expand()` and `minimatch.braceExpand()`, respectively)_
484484

485485
| **Pattern** | **braces** | **[minimatch][]** |
486-
| --- | --- | --- |
486+
| --------------- | --------------------------- | ---------------------------- |
487487
| `{1..10000000}` | `78.89 MB` (2s 698ms 642μs) | `78.89 MB` (18s 601ms 974μs) |
488488
| `{1..1000000}` | `6.89 MB` (458ms 576μs) | `6.89 MB` (1s 491ms 621μs) |
489489
| `{1..100000}` | `588.89 kB` (20ms 728μs) | `588.89 kB` (156ms 919μs) |
@@ -510,37 +510,30 @@ npm i -d && npm benchmark
510510
Braces is more accurate, without sacrificing performance.
511511

512512
```bash
513-
# range (expanded)
514-
braces x 29,040 ops/sec ±3.69% (91 runs sampled))
515-
minimatch x 4,735 ops/sec ±1.28% (90 runs sampled)
516-
517-
# range (optimized for regex)
518-
braces x 382,878 ops/sec ±0.56% (94 runs sampled)
519-
minimatch x 1,040 ops/sec ±0.44% (93 runs sampled)
520-
521-
# nested ranges (expanded)
522-
braces x 19,744 ops/sec ±2.27% (92 runs sampled))
523-
minimatch x 4,579 ops/sec ±0.50% (93 runs sampled)
524-
525-
# nested ranges (optimized for regex)
526-
braces x 246,019 ops/sec ±2.02% (93 runs sampled)
527-
minimatch x 1,028 ops/sec ±0.39% (94 runs sampled)
528-
529-
# set (expanded)
530-
braces x 138,641 ops/sec ±0.53% (95 runs sampled)
531-
minimatch x 219,582 ops/sec ±0.98% (94 runs sampled)
532-
533-
# set (optimized for regex)
534-
braces x 388,408 ops/sec ±0.41% (95 runs sampled)
535-
minimatch x 44,724 ops/sec ±0.91% (89 runs sampled)
536-
537-
# nested sets (expanded)
538-
braces x 84,966 ops/sec ±0.48% (94 runs sampled)
539-
minimatch x 140,720 ops/sec ±0.37% (95 runs sampled)
540-
541-
# nested sets (optimized for regex)
542-
braces x 263,340 ops/sec ±2.06% (92 runs sampled)
543-
minimatch x 28,714 ops/sec ±0.40% (90 runs sampled)
513+
● expand - range (expanded)
514+
braces x 53,167 ops/sec ±0.12% (102 runs sampled)
515+
minimatch x 11,378 ops/sec ±0.10% (102 runs sampled)
516+
● expand - range (optimized for regex)
517+
braces x 373,442 ops/sec ±0.04% (100 runs sampled)
518+
minimatch x 3,262 ops/sec ±0.18% (100 runs sampled)
519+
● expand - nested ranges (expanded)
520+
braces x 33,921 ops/sec ±0.09% (99 runs sampled)
521+
minimatch x 10,855 ops/sec ±0.28% (100 runs sampled)
522+
● expand - nested ranges (optimized for regex)
523+
braces x 287,479 ops/sec ±0.52% (98 runs sampled)
524+
minimatch x 3,219 ops/sec ±0.28% (101 runs sampled)
525+
● expand - set (expanded)
526+
braces x 238,243 ops/sec ±0.19% (97 runs sampled)
527+
minimatch x 538,268 ops/sec ±0.31% (96 runs sampled)
528+
● expand - set (optimized for regex)
529+
braces x 321,844 ops/sec ±0.10% (97 runs sampled)
530+
minimatch x 140,600 ops/sec ±0.15% (100 runs sampled)
531+
● expand - nested sets (expanded)
532+
braces x 165,371 ops/sec ±0.42% (96 runs sampled)
533+
minimatch x 337,720 ops/sec ±0.28% (100 runs sampled)
534+
● expand - nested sets (optimized for regex)
535+
braces x 242,948 ops/sec ±0.12% (99 runs sampled)
536+
minimatch x 87,403 ops/sec ±0.79% (96 runs sampled)
544537
```
545538

546539
## About
@@ -578,28 +571,28 @@ $ npm install -g verbose/verb#dev verb-generate-readme && verb
578571

579572
### Contributors
580573

581-
| **Commits** | **Contributor** |
582-
| --- | --- |
583-
| 197 | [jonschlinkert](https://github.com/jonschlinkert) |
584-
| 4 | [doowb](https://github.com/doowb) |
585-
| 1 | [es128](https://github.com/es128) |
586-
| 1 | [eush77](https://github.com/eush77) |
587-
| 1 | [hemanth](https://github.com/hemanth) |
588-
| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
574+
| **Commits** | **Contributor** |
575+
| ----------- | ------------------------------------------------------------- |
576+
| 197 | [jonschlinkert](https://github.com/jonschlinkert) |
577+
| 4 | [doowb](https://github.com/doowb) |
578+
| 1 | [es128](https://github.com/es128) |
579+
| 1 | [eush77](https://github.com/eush77) |
580+
| 1 | [hemanth](https://github.com/hemanth) |
581+
| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
589582

590583
### Author
591584

592585
**Jon Schlinkert**
593586

594-
* [GitHub Profile](https://github.com/jonschlinkert)
595-
* [Twitter Profile](https://twitter.com/jonschlinkert)
596-
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
587+
- [GitHub Profile](https://github.com/jonschlinkert)
588+
- [Twitter Profile](https://twitter.com/jonschlinkert)
589+
- [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
597590

598591
### License
599592

600593
Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
601594
Released under the [MIT License](LICENSE).
602595

603-
***
596+
---
604597

605-
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._
598+
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._

0 commit comments

Comments
 (0)