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.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.
Brace patterns are great for matching ranges. Users (and implementors) shouldn't have to think about whether or not they will break their application (or yours) from accidentally defining an aggressive brace pattern. Braces is the only library that offers a solution to this problem.
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.
console.log(braces('a/{b,c}/d', { maxLength:3 })); //=> throws an error
options.expand
Type: Boolean
Default: undefined
Description: Generate an "expanded" brace pattern (this option is unncessary with the .expand method, which does the same thing).
Description: Duplicates are removed by default. To keep duplicates, pass {nodupes: false} on the options
options.rangeLimit
Type: Number
Default: 250
Description: When braces.expand() is used, or options.expand is true, brace patterns will automatically be optimized when the difference between the range minimum and range maximum exceeds the rangeLimit. This is to prevent huge ranges from freezing your application.
You can set this to any number, or change options.rangeLimit to Inifinity to disable this altogether.
var range =braces.expand('x{a..e}y', {transform:function(str) {return'foo'+ str; }});console.log(range);//=> [ 'xfooay', 'xfooby', 'xfoocy', 'xfoody', 'xfooey' ]
options.quantifiers
Type: Boolean
Default: undefined
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.
Unfortunately, regex quantifiers happen to share the same syntax as Bash lists
The quantifiers option tells braces to detect when regex quantifiers are defined in the given pattern, and not to try to expand them as lists.
Description: Strip backslashes that were used for escaping from the result.
What is "brace expansion"?
Brace 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).
In addition to "expansion", braces are also used for matching. In other words:
lists: which are defined using comma-separated values inside curly braces: {a,b,c}
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".
Here are some example brace patterns to illustrate how they work:
Sets
{a,b,c} => a b c
{a,b,c}{1,2} => a1 a2 b1 b2 c1 c2
Sequences
{1..9} => 1 2 3 4 5 6 7 8 9
{4..-4} => 4 3 2 1 0 -1 -2 -3 -4
{1..20..3} => 1 4 7 10 13 16 19
{a..j} => a b c d e f g h i j
{j..a} => j i h g f e d c b a
{a..z..3} => a d g j m p s v y
Combination
Sets and sequences can be mixed together or used along with any other strings.
The fact that braces can be "expanded" from relatively simple patterns makes them ideal for quickly generating test fixtures, file paths, and similar use cases.
Brace matching
In addition to expansion, brace patterns are also useful for performing regular-expression-like matching.
For example, the pattern foo/{1..3}/bar would match any of following strings:
foo/1/bar
foo/2/bar
foo/3/bar
But not:
baz/1/qux
baz/2/qux
baz/3/qux
Braces can also be combined with glob patterns to perform more advanced wildcard matching. For example, the pattern */{1..3}/* would match any of following strings:
Although 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.
tldr
"brace bombs"
brace expansion can eat up a huge amount of processing resources
as brace patterns increase linearly in size, the system resources required to expand the pattern increase exponentially
users can accidentally (or intentially) exhaust your system's resources resulting in the equivalent of a DoS attack (bonus: no programming knowledge is required!)
For a more detailed explanation with examples, see the geometric complexity section.
The solution
Jump to the performance section to see how Braces solves this problem in comparison to other libraries.
Geometric complexity
At 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).
For example, the following sets demonstrate quadratic (O(n^2)) complexity:
Braces is not only screaming fast, it's also more accurate the other brace expansion libraries.
Better algorithms
Fortunately there is a solution to the "brace bomb" problem: don't expand brace patterns into an array when they're used for matching.
Instead, convert the pattern into an optimized regular expression. This is easier said than done, and braces is the only library that does this currently.
The proof is in the numbers
Minimatch gets exponentially slower as patterns increase in complexity, braces does not. The following results were generated using braces() and minimatch.braceExpand(), respectively.
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running Tests
Running 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:
$ npm install && npm test
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command: