AK-21/Graphite-Industrial-Intelligence
0
1# braces [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [](https://www.npmjs.com/package/braces) [](https://npmjs.org/package/braces) [](https://npmjs.org/package/braces) [](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## Install8 9Install with [npm](https://www.npmjs.com/):10 11```sh12$ npm install --save braces13```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## Usage34 35The main export is a function that takes one or more brace `patterns` and `options`.36 37```js38const 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. Compilation49 50By default, brace patterns are compiled into strings that are optimized for creating regular expressions and matching.51 52**Compiled**53 54```js55console.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```js66console.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### Lists74 75Expand lists (like Bash "sets"):76 77```js78console.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### Sequences86 87Expand ranges of characters (like Bash "sequences"):88 89```js90console.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 ranges96console.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 ranges103 104Steps, or increments, may be used with ranges:105 106```js107console.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### Nesting117 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```js123console.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```js133console.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### Escaping141 142**Escaping braces**143 144A brace pattern will not be expanded or evaluted if _either the opening or closing brace is escaped_:145 146```js147console.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```js159console.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```js171console.log(braces.expand('a{b}c'));172//=> ['a{b}c']173```174 175## Options176 177### options.maxLength178 179**Type**: `Number`180 181**Default**: `10,000`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```js186console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error187```188 189### options.expand190 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```js198console.log(braces('a/{b,c}/d', { expand: true }));199//=> [ 'a/b/d', 'a/c/d' ]200```201 202### options.nodupes203 204**Type**: `Boolean`205 206**Default**: `undefined`207 208**Description**: Remove duplicates from the returned array.209 210### options.rangeLimit211 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```js223// pattern exceeds the "rangeLimit", so it's optimized automatically224console.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 optimized228console.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.transform233 234**Type**: `Function`235 236**Default**: `undefined`237 238**Description**: Customize range expansion.239 240**Example: Transforming non-numeric values**241 242```js243const 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```js256const numeric = braces.expand('{1..5}', {257 transform(value) {258 // when numeric values are passed, "value" is a number259 return 'foo/' + value * 2;260 },261});262console.log(numeric);263//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]264```265 266### options.quantifiers267 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```js281const 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.keepEscaping291 292**Type**: `Boolean`293 294**Default**: `undefined`295 296**Description**: Do not 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 lists305- [brace matching](#brace-matching) is for filtering existing lists306 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 c321{a,b,c}{1,2} => a1 a2 b1 b2 c1 c2322```323 324**Sequences**325 326```327{1..9} => 1 2 3 4 5 6 7 8 9328{4..-4} => 4 3 2 1 0 -1 -2 -3 -4329{1..20..3} => 1 4 7 10 13 16 19330{a..j} => a b c d e f g h i j331{j..a} => j i h g f e d c b a332{a..z..3} => a d g j m p s v y333```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 c3341foo/{a,b,c}/bar => foo/a/bar foo/b/bar foo/c/bar342```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 matching347 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/bar354foo/2/bar355foo/3/bar356```357 358But not:359 360```361baz/1/qux362baz/2/qux363baz/3/qux364```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/bar370foo/2/bar371foo/3/bar372baz/1/qux373baz/2/qux374baz/3/qux375```376 377## Brace matching pitfalls378 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### tldr382 383**"brace bombs"**384 385- brace expansion can eat up a huge amount of processing resources386- as brace patterns increase _linearly in size_, the system resources required to expand the pattern increase exponentially387- 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 solution392 393Jump to the [performance section](#performance) to see how Braces solves this problem in comparison to other libraries.394 395### Geometric complexity396 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 24403{1,2}{3,4}{5,6} => (2X2X2) => 135 136 145 146 235 236 245 246404```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 248410 249 257 258 259 267 268 269 347 348 349 357411 358 359 367 368 369412```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## Performance434 435Braces is not only screaming fast, it's also more accurate the other brace expansion libraries.436 437### Better algorithms438 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 algorithms468 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## Benchmarks487 488### Running benchmarks489 490Install dev dependencies:491 492```bash493npm i -d && npm benchmark494```495 496### Latest results497 498Braces is more accurate, without sacrificing performance.499 500```bash501● expand - range (expanded)502 braces x 53,167 ops/sec ±0.12% (102 runs sampled)503 minimatch x 11,378 ops/sec ±0.10% (102 runs sampled)504● expand - range (optimized for regex)505 braces x 373,442 ops/sec ±0.04% (100 runs sampled)506 minimatch x 3,262 ops/sec ±0.18% (100 runs sampled)507● expand - nested ranges (expanded)508 braces x 33,921 ops/sec ±0.09% (99 runs sampled)509 minimatch x 10,855 ops/sec ±0.28% (100 runs sampled)510● expand - nested ranges (optimized for regex)511 braces x 287,479 ops/sec ±0.52% (98 runs sampled)512 minimatch x 3,219 ops/sec ±0.28% (101 runs sampled)513● expand - set (expanded)514 braces x 238,243 ops/sec ±0.19% (97 runs sampled)515 minimatch x 538,268 ops/sec ±0.31% (96 runs sampled)516● expand - set (optimized for regex)517 braces x 321,844 ops/sec ±0.10% (97 runs sampled)518 minimatch x 140,600 ops/sec ±0.15% (100 runs sampled)519● expand - nested sets (expanded)520 braces x 165,371 ops/sec ±0.42% (96 runs sampled)521 minimatch x 337,720 ops/sec ±0.28% (100 runs sampled)522● expand - nested sets (optimized for regex)523 braces x 242,948 ops/sec ±0.12% (99 runs sampled)524 minimatch x 87,403 ops/sec ±0.79% (96 runs sampled)525```526 527## About528 529<details>530<summary><strong>Contributing</strong></summary>531 532Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).533 534</details>535 536<details>537<summary><strong>Running Tests</strong></summary>538 539Running 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:540 541```sh542$ npm install && npm test543```544 545</details>546 547<details>548<summary><strong>Building docs</strong></summary>549 550_(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.)_551 552To generate the readme, run the following command:553 554```sh555$ npm install -g verbose/verb#dev verb-generate-readme && verb556```557 558</details>559 560### Contributors561 562| **Commits** | **Contributor** |563| ----------- | ------------------------------------------------------------- |564| 197 | [jonschlinkert](https://github.com/jonschlinkert) |565| 4 | [doowb](https://github.com/doowb) |566| 1 | [es128](https://github.com/es128) |567| 1 | [eush77](https://github.com/eush77) |568| 1 | [hemanth](https://github.com/hemanth) |569| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |570 571### Author572 573**Jon Schlinkert**574 575- [GitHub Profile](https://github.com/jonschlinkert)576- [Twitter Profile](https://twitter.com/jonschlinkert)577- [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)578 579### License580 581Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).582Released under the [MIT License](LICENSE).583 584---585 586_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._587