source: trip-planner-front/node_modules/braces/README.md@ 1ad8e64

Last change on this file since 1ad8e64 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 20.6 KB
Line 
1# braces [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/braces.svg?style=flat)](https://www.npmjs.com/package/braces) [![NPM monthly downloads](https://img.shields.io/npm/dm/braces.svg?style=flat)](https://npmjs.org/package/braces) [![NPM total downloads](https://img.shields.io/npm/dt/braces.svg?style=flat)](https://npmjs.org/package/braces) [![Linux Build Status](https://img.shields.io/travis/micromatch/braces.svg?style=flat&label=Travis)](https://travis-ci.org/micromatch/braces)
2
3> Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support for the Bash 4.3 braces specification, without sacrificing speed.
4
5Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
6
7## Install
8
9Install with [npm](https://www.npmjs.com/):
10
11```sh
12$ npm install --save braces
13```
14
15## v3.0.0 Released!!
16
17See the [changelog](CHANGELOG.md) for details.
18
19## Why use braces?
20
21Brace patterns make globs more powerful by adding the ability to match specific ranges and sequences of characters.
22
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.
32
33## Usage
34
35The main export is a function that takes one or more brace `patterns` and `options`.
36
37```js
38const braces = require('braces');
39// braces(patterns[, options]);
40
41console.log(braces(['{01..05}', '{a..e}']));
42//=> ['(0[1-5])', '([a-e])']
43
44console.log(braces(['{01..05}', '{a..e}'], { expand: true }));
45//=> ['01', '02', '03', '04', '05', 'a', 'b', 'c', 'd', 'e']
46```
47
48### Brace Expansion vs. Compilation
49
50By default, brace patterns are compiled into strings that are optimized for creating regular expressions and matching.
51
52**Compiled**
53
54```js
55console.log(braces('a/{x,y,z}/b'));
56//=> ['a/(x|y|z)/b']
57console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
58//=> [ 'a/(0[1-9]|1[0-9]|20)/b', 'a/([1-5])/b' ]
59```
60
61**Expanded**
62
63Enable brace expansion by setting the `expand` option to true, or by using [braces.expand()](#expand) (returns an array similar to what you'd expect from Bash, or `echo {1..5}`, or [minimatch](https://github.com/isaacs/minimatch)):
64
65```js
66console.log(braces('a/{x,y,z}/b', { expand: true }));
67//=> ['a/x/b', 'a/y/b', 'a/z/b']
68
69console.log(braces.expand('{01..10}'));
70//=> ['01','02','03','04','05','06','07','08','09','10']
71```
72
73### Lists
74
75Expand lists (like Bash "sets"):
76
77```js
78console.log(braces('a/{foo,bar,baz}/*.js'));
79//=> ['a/(foo|bar|baz)/*.js']
80
81console.log(braces.expand('a/{foo,bar,baz}/*.js'));
82//=> ['a/foo/*.js', 'a/bar/*.js', 'a/baz/*.js']
83```
84
85### Sequences
86
87Expand ranges of characters (like Bash "sequences"):
88
89```js
90console.log(braces.expand('{1..3}')); // ['1', '2', '3']
91console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
92console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
93console.log(braces('foo/{a..c}', { expand: true })); // ['foo/a', 'foo/b', 'foo/c']
94
95// supports zero-padded ranges
96console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
97console.log(braces('a/{001..300}/b')); //=> ['a/(0{2}[1-9]|0[1-9][0-9]|[12][0-9]{2}|300)/b']
98```
99
100See [fill-range](https://github.com/jonschlinkert/fill-range) for all available range-expansion options.
101
102### Steppped ranges
103
104Steps, or increments, may be used with ranges:
105
106```js
107console.log(braces.expand('{2..10..2}'));
108//=> ['2', '4', '6', '8', '10']
109
110console.log(braces('{2..10..2}'));
111//=> ['(2|4|6|8|10)']
112```
113
114When the [.optimize](#optimize) method is used, or [options.optimize](#optionsoptimize) is set to true, sequences are passed to [to-regex-range](https://github.com/jonschlinkert/to-regex-range) for expansion.
115
116### Nesting
117
118Brace patterns may be nested. The results of each expanded string are not sorted, and left to right order is preserved.
119
120**"Expanded" braces**
121
122```js
123console.log(braces.expand('a{b,c,/{x,y}}/e'));
124//=> ['ab/e', 'ac/e', 'a/x/e', 'a/y/e']
125
126console.log(braces.expand('a/{x,{1..5},y}/c'));
127//=> ['a/x/c', 'a/1/c', 'a/2/c', 'a/3/c', 'a/4/c', 'a/5/c', 'a/y/c']
128```
129
130**"Optimized" braces**
131
132```js
133console.log(braces('a{b,c,/{x,y}}/e'));
134//=> ['a(b|c|/(x|y))/e']
135
136console.log(braces('a/{x,{1..5},y}/c'));
137//=> ['a/(x|([1-5])|y)/c']
138```
139
140### Escaping
141
142**Escaping braces**
143
144A brace pattern will not be expanded or evaluted if _either the opening or closing brace is escaped_:
145
146```js
147console.log(braces.expand('a\\{d,c,b}e'));
148//=> ['a{d,c,b}e']
149
150console.log(braces.expand('a{d,c,b\\}e'));
151//=> ['a{d,c,b}e']
152```
153
154**Escaping commas**
155
156Commas inside braces may also be escaped:
157
158```js
159console.log(braces.expand('a{b\\,c}d'));
160//=> ['a{b,c}d']
161
162console.log(braces.expand('a{d\\,c,b}e'));
163//=> ['ad,ce', 'abe']
164```
165
166**Single items**
167
168Following bash conventions, a brace pattern is also not expanded when it contains a single character:
169
170```js
171console.log(braces.expand('a{b}c'));
172//=> ['a{b}c']
173```
174
175## Options
176
177### options.maxLength
178
179**Type**: `Number`
180
181**Default**: `65,536`
182
183**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.
184
185```js
186console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error
187```
188
189### options.expand
190
191**Type**: `Boolean`
192
193**Default**: `undefined`
194
195**Description**: Generate an "expanded" brace pattern (alternatively you can use the `braces.expand()` method, which does the same thing).
196
197```js
198console.log(braces('a/{b,c}/d', { expand: true }));
199//=> [ 'a/b/d', 'a/c/d' ]
200```
201
202### options.nodupes
203
204**Type**: `Boolean`
205
206**Default**: `undefined`
207
208**Description**: Remove duplicates from the returned array.
209
210### options.rangeLimit
211
212**Type**: `Number`
213
214**Default**: `1000`
215
216**Description**: To prevent malicious patterns from being passed by users, an error is thrown when `braces.expand()` is used or `options.expand` is true and the generated range will exceed the `rangeLimit`.
217
218You can customize `options.rangeLimit` or set it to `Inifinity` to disable this altogether.
219
220**Examples**
221
222```js
223// pattern exceeds the "rangeLimit", so it's optimized automatically
224console.log(braces.expand('{1..1000}'));
225//=> ['([1-9]|[1-9][0-9]{1,2}|1000)']
226
227// pattern does not exceed "rangeLimit", so it's NOT optimized
228console.log(braces.expand('{1..100}'));
229//=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '52', '53', '54', '55', '56', '57', '58', '59', '60', '61', '62', '63', '64', '65', '66', '67', '68', '69', '70', '71', '72', '73', '74', '75', '76', '77', '78', '79', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99', '100']
230```
231
232### options.transform
233
234**Type**: `Function`
235
236**Default**: `undefined`
237
238**Description**: Customize range expansion.
239
240**Example: Transforming non-numeric values**
241
242```js
243const alpha = braces.expand('x/{a..e}/y', {
244 transform(value, index) {
245 // When non-numeric values are passed, "value" is a character code.
246 return 'foo/' + String.fromCharCode(value) + '-' + index;
247 }
248});
249console.log(alpha);
250//=> [ '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' ]
251```
252
253**Example: Transforming numeric values**
254
255```js
256const numeric = braces.expand('{1..5}', {
257 transform(value) {
258 // when numeric values are passed, "value" is a number
259 return 'foo/' + value * 2;
260 }
261});
262console.log(numeric);
263//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]
264```
265
266### options.quantifiers
267
268**Type**: `Boolean`
269
270**Default**: `undefined`
271
272**Description**: In regular expressions, quanitifiers can be used to specify how many times a token can be repeated. For example, `a{1,3}` will match the letter `a` one to three times.
273
274Unfortunately, regex quantifiers happen to share the same syntax as [Bash lists](#lists)
275
276The `quantifiers` option tells braces to detect when [regex quantifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#quantifiers) are defined in the given pattern, and not to try to expand them as lists.
277
278**Examples**
279
280```js
281const braces = require('braces');
282console.log(braces('a/b{1,3}/{x,y,z}'));
283//=> [ 'a/b(1|3)/(x|y|z)' ]
284console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true}));
285//=> [ 'a/b{1,3}/(x|y|z)' ]
286console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true, expand: true}));
287//=> [ 'a/b{1,3}/x', 'a/b{1,3}/y', 'a/b{1,3}/z' ]
288```
289
290### options.unescape
291
292**Type**: `Boolean`
293
294**Default**: `undefined`
295
296**Description**: Strip backslashes that were used for escaping from the result.
297
298## What is "brace expansion"?
299
300Brace expansion is a type of parameter expansion that was made popular by unix shells for generating lists of strings, as well as regex-like matching when used alongside wildcards (globs).
301
302In addition to "expansion", braces are also used for matching. In other words:
303
304* [brace expansion](#brace-expansion) is for generating new lists
305* [brace matching](#brace-matching) is for filtering existing lists
306
307<details>
308<summary><strong>More about brace expansion</strong> (click to expand)</summary>
309
310There are two main types of brace expansion:
311
3121. **lists**: which are defined using comma-separated values inside curly braces: `{a,b,c}`
3132. **sequences**: which are defined using a starting value and an ending value, separated by two dots: `a{1..3}b`. Optionally, a third argument may be passed to define a "step" or increment to use: `a{1..100..10}b`. These are also sometimes referred to as "ranges".
314
315Here are some example brace patterns to illustrate how they work:
316
317**Sets**
318
319```
320{a,b,c} => a b c
321{a,b,c}{1,2} => a1 a2 b1 b2 c1 c2
322```
323
324**Sequences**
325
326```
327{1..9} => 1 2 3 4 5 6 7 8 9
328{4..-4} => 4 3 2 1 0 -1 -2 -3 -4
329{1..20..3} => 1 4 7 10 13 16 19
330{a..j} => a b c d e f g h i j
331{j..a} => j i h g f e d c b a
332{a..z..3} => a d g j m p s v y
333```
334
335**Combination**
336
337Sets and sequences can be mixed together or used along with any other strings.
338
339```
340{a,b,c}{1..3} => a1 a2 a3 b1 b2 b3 c1 c2 c3
341foo/{a,b,c}/bar => foo/a/bar foo/b/bar foo/c/bar
342```
343
344The fact that braces can be "expanded" from relatively simple patterns makes them ideal for quickly generating test fixtures, file paths, and similar use cases.
345
346## Brace matching
347
348In addition to _expansion_, brace patterns are also useful for performing regular-expression-like matching.
349
350For example, the pattern `foo/{1..3}/bar` would match any of following strings:
351
352```
353foo/1/bar
354foo/2/bar
355foo/3/bar
356```
357
358But not:
359
360```
361baz/1/qux
362baz/2/qux
363baz/3/qux
364```
365
366Braces can also be combined with [glob patterns](https://github.com/jonschlinkert/micromatch) to perform more advanced wildcard matching. For example, the pattern `*/{1..3}/*` would match any of following strings:
367
368```
369foo/1/bar
370foo/2/bar
371foo/3/bar
372baz/1/qux
373baz/2/qux
374baz/3/qux
375```
376
377## Brace matching pitfalls
378
379Although brace patterns offer a user-friendly way of matching ranges or sets of strings, there are also some major disadvantages and potential risks you should be aware of.
380
381### tldr
382
383**"brace bombs"**
384
385* brace expansion can eat up a huge amount of processing resources
386* as brace patterns increase _linearly in size_, the system resources required to expand the pattern increase exponentially
387* users can accidentally (or intentially) exhaust your system's resources resulting in the equivalent of a DoS attack (bonus: no programming knowledge is required!)
388
389For a more detailed explanation with examples, see the [geometric complexity](#geometric-complexity) section.
390
391### The solution
392
393Jump to the [performance section](#performance) to see how Braces solves this problem in comparison to other libraries.
394
395### Geometric complexity
396
397At minimum, brace patterns with sets limited to two elements have quadradic or `O(n^2)` complexity. But the complexity of the algorithm increases exponentially as the number of sets, _and elements per set_, increases, which is `O(n^c)`.
398
399For example, the following sets demonstrate quadratic (`O(n^2)`) complexity:
400
401```
402{1,2}{3,4} => (2X2) => 13 14 23 24
403{1,2}{3,4}{5,6} => (2X2X2) => 135 136 145 146 235 236 245 246
404```
405
406But add an element to a set, and we get a n-fold Cartesian product with `O(n^c)` complexity:
407
408```
409{1,2,3}{4,5,6}{7,8,9} => (3X3X3) => 147 148 149 157 158 159 167 168 169 247 248
410 249 257 258 259 267 268 269 347 348 349 357
411 358 359 367 368 369
412```
413
414Now, imagine how this complexity grows given that each element is a n-tuple:
415
416```
417{1..100}{1..100} => (100X100) => 10,000 elements (38.4 kB)
418{1..100}{1..100}{1..100} => (100X100X100) => 1,000,000 elements (5.76 MB)
419```
420
421Although these examples are clearly contrived, they demonstrate how brace patterns can quickly grow out of control.
422
423**More information**
424
425Interested in learning more about brace expansion?
426
427* [linuxjournal/bash-brace-expansion](http://www.linuxjournal.com/content/bash-brace-expansion)
428* [rosettacode/Brace_expansion](https://rosettacode.org/wiki/Brace_expansion)
429* [cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
430
431</details>
432
433## Performance
434
435Braces is not only screaming fast, it's also more accurate the other brace expansion libraries.
436
437### Better algorithms
438
439Fortunately there is a solution to the ["brace bomb" problem](#brace-matching-pitfalls): _don't expand brace patterns into an array when they're used for matching_.
440
441Instead, convert the pattern into an optimized regular expression. This is easier said than done, and braces is the only library that does this currently.
442
443**The proof is in the numbers**
444
445Minimatch gets exponentially slower as patterns increase in complexity, braces does not. The following results were generated using `braces()` and `minimatch.braceExpand()`, respectively.
446
447| **Pattern** | **braces** | **[minimatch][]** |
448| --- | --- | --- |
449| `{1..9007199254740991}`[^1] | `298 B` (5ms 459μs)| N/A (freezes) |
450| `{1..1000000000000000}` | `41 B` (1ms 15μs) | N/A (freezes) |
451| `{1..100000000000000}` | `40 B` (890μs) | N/A (freezes) |
452| `{1..10000000000000}` | `39 B` (2ms 49μs) | N/A (freezes) |
453| `{1..1000000000000}` | `38 B` (608μs) | N/A (freezes) |
454| `{1..100000000000}` | `37 B` (397μs) | N/A (freezes) |
455| `{1..10000000000}` | `35 B` (983μs) | N/A (freezes) |
456| `{1..1000000000}` | `34 B` (798μs) | N/A (freezes) |
457| `{1..100000000}` | `33 B` (733μs) | N/A (freezes) |
458| `{1..10000000}` | `32 B` (5ms 632μs) | `78.89 MB` (16s 388ms 569μs) |
459| `{1..1000000}` | `31 B` (1ms 381μs) | `6.89 MB` (1s 496ms 887μs) |
460| `{1..100000}` | `30 B` (950μs) | `588.89 kB` (146ms 921μs) |
461| `{1..10000}` | `29 B` (1ms 114μs) | `48.89 kB` (14ms 187μs) |
462| `{1..1000}` | `28 B` (760μs) | `3.89 kB` (1ms 453μs) |
463| `{1..100}` | `22 B` (345μs) | `291 B` (196μs) |
464| `{1..10}` | `10 B` (533μs) | `20 B` (37μs) |
465| `{1..3}` | `7 B` (190μs) | `5 B` (27μs) |
466
467### Faster algorithms
468
469When you need expansion, braces is still much faster.
470
471_(the following results were generated using `braces.expand()` and `minimatch.braceExpand()`, respectively)_
472
473| **Pattern** | **braces** | **[minimatch][]** |
474| --- | --- | --- |
475| `{1..10000000}` | `78.89 MB` (2s 698ms 642μs) | `78.89 MB` (18s 601ms 974μs) |
476| `{1..1000000}` | `6.89 MB` (458ms 576μs) | `6.89 MB` (1s 491ms 621μs) |
477| `{1..100000}` | `588.89 kB` (20ms 728μs) | `588.89 kB` (156ms 919μs) |
478| `{1..10000}` | `48.89 kB` (2ms 202μs) | `48.89 kB` (13ms 641μs) |
479| `{1..1000}` | `3.89 kB` (1ms 796μs) | `3.89 kB` (1ms 958μs) |
480| `{1..100}` | `291 B` (424μs) | `291 B` (211μs) |
481| `{1..10}` | `20 B` (487μs) | `20 B` (72μs) |
482| `{1..3}` | `5 B` (166μs) | `5 B` (27μs) |
483
484If you'd like to run these comparisons yourself, see [test/support/generate.js](test/support/generate.js).
485
486## Benchmarks
487
488### Running benchmarks
489
490Install dev dependencies:
491
492```bash
493npm i -d && npm benchmark
494```
495
496### Latest results
497
498Braces is more accurate, without sacrificing performance.
499
500```bash
501# range (expanded)
502 braces x 29,040 ops/sec ±3.69% (91 runs sampled))
503 minimatch x 4,735 ops/sec ±1.28% (90 runs sampled)
504
505# range (optimized for regex)
506 braces x 382,878 ops/sec ±0.56% (94 runs sampled)
507 minimatch x 1,040 ops/sec ±0.44% (93 runs sampled)
508
509# nested ranges (expanded)
510 braces x 19,744 ops/sec ±2.27% (92 runs sampled))
511 minimatch x 4,579 ops/sec ±0.50% (93 runs sampled)
512
513# nested ranges (optimized for regex)
514 braces x 246,019 ops/sec ±2.02% (93 runs sampled)
515 minimatch x 1,028 ops/sec ±0.39% (94 runs sampled)
516
517# set (expanded)
518 braces x 138,641 ops/sec ±0.53% (95 runs sampled)
519 minimatch x 219,582 ops/sec ±0.98% (94 runs sampled)
520
521# set (optimized for regex)
522 braces x 388,408 ops/sec ±0.41% (95 runs sampled)
523 minimatch x 44,724 ops/sec ±0.91% (89 runs sampled)
524
525# nested sets (expanded)
526 braces x 84,966 ops/sec ±0.48% (94 runs sampled)
527 minimatch x 140,720 ops/sec ±0.37% (95 runs sampled)
528
529# nested sets (optimized for regex)
530 braces x 263,340 ops/sec ±2.06% (92 runs sampled)
531 minimatch x 28,714 ops/sec ±0.40% (90 runs sampled)
532```
533
534## About
535
536<details>
537<summary><strong>Contributing</strong></summary>
538
539Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
540
541</details>
542
543<details>
544<summary><strong>Running Tests</strong></summary>
545
546Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
547
548```sh
549$ npm install && npm test
550```
551
552</details>
553
554<details>
555<summary><strong>Building docs</strong></summary>
556
557_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
558
559To generate the readme, run the following command:
560
561```sh
562$ npm install -g verbose/verb#dev verb-generate-readme && verb
563```
564
565</details>
566
567### Contributors
568
569| **Commits** | **Contributor** |
570| --- | --- |
571| 197 | [jonschlinkert](https://github.com/jonschlinkert) |
572| 4 | [doowb](https://github.com/doowb) |
573| 1 | [es128](https://github.com/es128) |
574| 1 | [eush77](https://github.com/eush77) |
575| 1 | [hemanth](https://github.com/hemanth) |
576| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |
577
578### Author
579
580**Jon Schlinkert**
581
582* [GitHub Profile](https://github.com/jonschlinkert)
583* [Twitter Profile](https://twitter.com/jonschlinkert)
584* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
585
586### License
587
588Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
589Released under the [MIT License](LICENSE).
590
591***
592
593_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._
Note: See TracBrowser for help on using the repository browser.