README.md
1# brace-expansion
2
3[Brace expansion](https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html),
4as known from sh/bash, in JavaScript.
5
6[](http://travis-ci.org/juliangruber/brace-expansion)
7[](https://www.npmjs.org/package/brace-expansion)
8[](https://greenkeeper.io/)
9
10[](https://ci.testling.com/juliangruber/brace-expansion)
11
12## Example
13
14```js
15var expand = require('brace-expansion');
16
17expand('file-{a,b,c}.jpg')
18// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']
19
20expand('-v{,,}')
21// => ['-v', '-v', '-v']
22
23expand('file{0..2}.jpg')
24// => ['file0.jpg', 'file1.jpg', 'file2.jpg']
25
26expand('file-{a..c}.jpg')
27// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']
28
29expand('file{2..0}.jpg')
30// => ['file2.jpg', 'file1.jpg', 'file0.jpg']
31
32expand('file{0..4..2}.jpg')
33// => ['file0.jpg', 'file2.jpg', 'file4.jpg']
34
35expand('file-{a..e..2}.jpg')
36// => ['file-a.jpg', 'file-c.jpg', 'file-e.jpg']
37
38expand('file{00..10..5}.jpg')
39// => ['file00.jpg', 'file05.jpg', 'file10.jpg']
40
41expand('{{A..C},{a..c}}')
42// => ['A', 'B', 'C', 'a', 'b', 'c']
43
44expand('ppp{,config,oe{,conf}}')
45// => ['ppp', 'pppconfig', 'pppoe', 'pppoeconf']
46```
47
48## API
49
50```js
51var expand = require('brace-expansion');
52```
53
54### var expanded = expand(str)
55
56Return an array of all possible and valid expansions of `str`. If none are
57found, `[str]` is returned.
58
59Valid expansions are:
60
61```js
62/^(.*,)+(.+)?$/
63// {a,b,...}
64```
65
66A comma separated list of options, like `{a,b}` or `{a,{b,c}}` or `{,a,}`.
67
68```js
69/^-?\d+\.\.-?\d+(\.\.-?\d+)?$/
70// {x..y[..incr]}
71```
72
73A numeric sequence from `x` to `y` inclusive, with optional increment.
74If `x` or `y` start with a leading `0`, all the numbers will be padded
75to have equal length. Negative numbers and backwards iteration work too.
76
77```js
78/^-?\d+\.\.-?\d+(\.\.-?\d+)?$/
79// {x..y[..incr]}
80```
81
82An alphabetic sequence from `x` to `y` inclusive, with optional increment.
83`x` and `y` must be exactly one character, and if given, `incr` must be a
84number.
85
86For compatibility reasons, the string `${` is not eligible for brace expansion.
87
88## Installation
89
90With [npm](https://npmjs.org) do:
91
92```bash
93npm install brace-expansion
94```
95
96## Contributors
97
98- [Julian Gruber](https://github.com/juliangruber)
99- [Isaac Z. Schlueter](https://github.com/isaacs)
100
101## Sponsors
102
103This module is proudly supported by my [Sponsors](https://github.com/juliangruber/sponsors)!
104
105Do you want to support modules like this to improve their quality, stability and weigh in on new features? Then please consider donating to my [Patreon](https://www.patreon.com/juliangruber). Not sure how much of my modules you're using? Try [feross/thanks](https://github.com/feross/thanks)!
106
107## Security contact information
108
109To report a security vulnerability, please use the
110[Tidelift security contact](https://tidelift.com/security).
111Tidelift will coordinate the fix and disclosure.
112
113## License
114
115(MIT)
116
117Copyright (c) 2013 Julian Gruber <julian@juliangruber.com>
118
119Permission is hereby granted, free of charge, to any person obtaining a copy of
120this software and associated documentation files (the "Software"), to deal in
121the Software without restriction, including without limitation the rights to
122use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
123of the Software, and to permit persons to whom the Software is furnished to do
124so, subject to the following conditions:
125
126The above copyright notice and this permission notice shall be included in all
127copies or substantial portions of the Software.
128
129THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
130IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
131FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
132AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
133LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
134OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
135SOFTWARE.
136
){kind=link}
){kind=link}
){kind=link}
){kind=link}
