www.aleph1.co.uk Git - yaffs-website/blob - node_modules/braces/README.md

   1 # braces [![NPM version](https://img.shields.io/npm/v/braces.svg?style=flat)](https://www.npmjs.com/package/braces) [![NPM downloads](https://img.shields.io/npm/dm/braces.svg?style=flat)](https://npmjs.org/package/braces) [![Build Status](https://img.shields.io/travis/jonschlinkert/braces.svg?style=flat)](https://travis-ci.org/jonschlinkert/braces)
   2
   3 Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification.
   4
   5 ## Install
   6
   7 Install with [npm](https://www.npmjs.com/):
   8
   9 ```sh
  10 $ npm install braces --save
  11 ```
  12
  13 ## Features
  14
  15 * Complete support for the braces part of the [Bash 4.3 Brace Expansion](www.gnu.org/software/bash/). Braces passes [all of the relevant unit tests](#bash-4-3-support) from the spec.
  16 * Expands comma-separated values: `a/{b,c}/d` => `['a/b/d', 'a/c/d']`
  17 * Expands alphabetical or numerical ranges: `{1..3}` => `['1', '2', '3']`
  18 * [Very fast](#benchmarks)
  19 * [Special characters](./patterns.md) can be used to generate interesting patterns.
  20
  21 ## Example usage
  22
  23 ```js
  24 var braces = require('braces');
  25
  26 braces('a/{x,y}/c{d}e')
  27 //=> ['a/x/cde', 'a/y/cde']
  28
  29 braces('a/b/c/{x,y}')
  30 //=> ['a/b/c/x', 'a/b/c/y']
  31
  32 braces('a/{x,{1..5},y}/c{d}e')
  33 //=> ['a/x/cde', 'a/1/cde', 'a/y/cde', 'a/2/cde', 'a/3/cde', 'a/4/cde', 'a/5/cde']
  34 ```
  35
  36 ### Use case: fixtures
  37
  38 > Use braces to generate test fixtures!
  39
  40 **Example**
  41
  42 ```js
  43 var braces = require('./');
  44 var path = require('path');
  45 var fs = require('fs');
  46
  47 braces('blah/{a..z}.js').forEach(function(fp) {
  48   if (!fs.existsSync(path.dirname(fp))) {
  49     fs.mkdirSync(path.dirname(fp));
  50   }
  51   fs.writeFileSync(fp, '');
  52 });
  53 ```
  54
  55 See the [tests](./test/test.js) for more examples and use cases (also see the [bash spec tests](./test/bash-mm-adjusted.js));
  56
  57 ### Range expansion
  58
  59 Uses [expand-range](https://github.com/jonschlinkert/expand-range) for range expansion.
  60
  61 ```js
  62 braces('a{1..3}b')
  63 //=> ['a1b', 'a2b', 'a3b']
  64
  65 braces('a{5..8}b')
  66 //=> ['a5b', 'a6b', 'a7b', 'a8b']
  67
  68 braces('a{00..05}b')
  69 //=> ['a00b', 'a01b', 'a02b', 'a03b', 'a04b', 'a05b']
  70
  71 braces('a{01..03}b')
  72 //=> ['a01b', 'a02b', 'a03b']
  73
  74 braces('a{000..005}b')
  75 //=> ['a000b', 'a001b', 'a002b', 'a003b', 'a004b', 'a005b']
  76
  77 braces('a{a..e}b')
  78 //=> ['aab', 'abb', 'acb', 'adb', 'aeb']
  79
  80 braces('a{A..E}b')
  81 //=> ['aAb', 'aBb', 'aCb', 'aDb', 'aEb']
  82 ```
  83
  84 Pass a function as the last argument to customize range expansions:
  85
  86 ```js
  87 var range = braces('x{a..e}y', function (str, i) {
  88   return String.fromCharCode(str) + i;
  89 });
  90
  91 console.log(range);
  92 //=> ['xa0y', 'xb1y', 'xc2y', 'xd3y', 'xe4y']
  93 ```
  94
  95 See [expand-range](https://github.com/jonschlinkert/expand-range) for benchmarks, tests and the full list of range expansion features.
  96
  97 ## Options
  98
  99 ### options.makeRe
 100
 101 Type: `Boolean`
 102
 103 Deafault: `false`
 104
 105 Return a regex-optimal string. If you're using braces to generate regex, this will result in dramatically faster performance.
 106
 107 **Examples**
 108
 109 With the default settings (`{makeRe: false}`):
 110
 111 ```js
 112 braces('{1..5}');
 113 //=> ['1', '2', '3', '4', '5']
 114 ```
 115
 116 With `{makeRe: true}`:
 117
 118 ```js
 119 braces('{1..5}', {makeRe: true});
 120 //=> ['[1-5]']
 121
 122 braces('{3..9..3}', {makeRe: true});
 123 //=> ['(3|6|9)']
 124 ```
 125
 126 ### options.bash
 127
 128 Type: `Boolean`
 129
 130 Default: `false`
 131
 132 Enables complete support for the Bash specification. The downside is a 20-25% speed decrease.
 133
 134 **Example**
 135
 136 Using the default setting (`{bash: false}`):
 137
 138 ```js
 139 braces('a{b}c');
 140 //=> ['abc']
 141 ```
 142
 143 In bash (and minimatch), braces with one item are not expanded. To get the same result with braces, set `{bash: true}`:
 144
 145 ```js
 146 braces('a{b}c', {bash: true});
 147 //=> ['a{b}c']
 148 ```
 149
 150 ### options.nodupes
 151
 152 Type: `Boolean`
 153
 154 Deafault: `true`
 155
 156 Duplicates are removed by default. To keep duplicates, pass `{nodupes: false}` on the options
 157
 158 ## Bash 4.3 Support
 159
 160 > Better support for Bash 4.3 than minimatch
 161
 162 This project has comprehensive unit tests, including tests coverted from [Bash 4.3](www.gnu.org/software/bash/). Currently only 8 of 102 unit tests fail, and
 163
 164 ## Run benchmarks
 165
 166 Install dev dependencies:
 167
 168 ```bash
 169 npm i -d && npm benchmark
 170 ```
 171
 172 ### Latest results
 173
 174 ```bash
 175 #1: escape.js
 176   brace-expansion.js x 114,934 ops/sec ±1.24% (93 runs sampled)
 177   braces.js x 342,254 ops/sec ±0.84% (90 runs sampled)
 178
 179 #2: exponent.js
 180   brace-expansion.js x 12,359 ops/sec ±0.86% (96 runs sampled)
 181   braces.js x 20,389 ops/sec ±0.71% (97 runs sampled)
 182
 183 #3: multiple.js
 184   brace-expansion.js x 114,469 ops/sec ±1.44% (94 runs sampled)
 185   braces.js x 401,621 ops/sec ±0.87% (91 runs sampled)
 186
 187 #4: nested.js
 188   brace-expansion.js x 102,769 ops/sec ±1.55% (92 runs sampled)
 189   braces.js x 314,088 ops/sec ±0.71% (98 runs sampled)
 190
 191 #5: normal.js
 192   brace-expansion.js x 157,577 ops/sec ±1.65% (91 runs sampled)
 193   braces.js x 1,115,950 ops/sec ±0.74% (94 runs sampled)
 194
 195 #6: range.js
 196   brace-expansion.js x 138,822 ops/sec ±1.71% (91 runs sampled)
 197   braces.js x 1,108,353 ops/sec ±0.85% (94 runs sampled)
 198 ```
 199
 200 ## Related projects
 201
 202 You might also be interested in these projects:
 203
 204 * [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See… [more](https://www.npmjs.com/package/expand-range) | [homepage](https://github.com/jonschlinkert/expand-range)
 205 * [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or multiplier to… [more](https://www.npmjs.com/package/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range)
 206 * [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/jonschlinkert/micromatch)
 207
 208 ## Contributing
 209
 210 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/braces/issues/new).
 211
 212 ## Building docs
 213
 214 Generate readme and API documentation with [verb](https://github.com/verbose/verb):
 215
 216 ```sh
 217 $ npm install verb && npm run docs
 218 ```
 219
 220 Or, if [verb](https://github.com/verbose/verb) is installed globally:
 221
 222 ```sh
 223 $ verb
 224 ```
 225
 226 ## Running tests
 227
 228 Install dev dependencies:
 229
 230 ```sh
 231 $ npm install -d && npm test
 232 ```
 233
 234 ## Author
 235
 236 **Jon Schlinkert**
 237
 238 * [github/jonschlinkert](https://github.com/jonschlinkert)
 239 * [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
 240
 241 ## License
 242
 243 Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
 244 Released under the [MIT license](https://github.com/jonschlinkert/braces/blob/master/LICENSE).
 245
 246 ***
 247
 248 _This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on May 21, 2016._