1# expand-brackets [![NPM version](https://img.shields.io/npm/v/expand-brackets.svg?style=flat)](https://www.npmjs.com/package/expand-brackets) [![NPM monthly downloads](https://img.shields.io/npm/dm/expand-brackets.svg?style=flat)](https://npmjs.org/package/expand-brackets) [![NPM total downloads](https://img.shields.io/npm/dt/expand-brackets.svg?style=flat)](https://npmjs.org/package/expand-brackets) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/expand-brackets.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/expand-brackets) [![Windows Build Status](https://img.shields.io/appveyor/ci/jonschlinkert/expand-brackets.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/jonschlinkert/expand-brackets) 2 3> Expand POSIX bracket expressions (character classes) in glob patterns. 4 5## Install 6 7Install with [npm](https://www.npmjs.com/): 8 9```sh 10$ npm install --save expand-brackets 11``` 12 13## Usage 14 15```js 16var brackets = require('expand-brackets'); 17brackets(string[, options]); 18``` 19 20**Params** 21 22The main export is a function that takes the following parameters: 23 24* `pattern` **{String}**: the pattern to convert 25* `options` **{Object}**: optionally supply an options object 26* `returns` **{String}**: returns a string that can be used to create a regex 27 28**Example** 29 30```js 31console.log(brackets('[![:lower:]]')); 32//=> '[^a-z]' 33``` 34 35## API 36 37### [brackets](index.js#L29) 38 39Parses the given POSIX character class `pattern` and returns a 40string that can be used for creating regular expressions for matching. 41 42**Params** 43 44* `pattern` **{String}** 45* `options` **{Object}** 46* `returns` **{Object}** 47 48### [.match](index.js#L54) 49 50Takes an array of strings and a POSIX character class pattern, and returns a new array with only the strings that matched the pattern. 51 52**Example** 53 54```js 55var brackets = require('expand-brackets'); 56console.log(brackets.match(['1', 'a', 'ab'], '[[:alpha:]]')); 57//=> ['a'] 58 59console.log(brackets.match(['1', 'a', 'ab'], '[[:alpha:]]+')); 60//=> ['a', 'ab'] 61``` 62 63**Params** 64 65* `arr` **{Array}**: Array of strings to match 66* `pattern` **{String}**: POSIX character class pattern(s) 67* `options` **{Object}** 68* `returns` **{Array}** 69 70### [.isMatch](index.js#L100) 71 72Returns true if the specified `string` matches the given brackets `pattern`. 73 74**Example** 75 76```js 77var brackets = require('expand-brackets'); 78 79console.log(brackets.isMatch('a.a', '[[:alpha:]].[[:alpha:]]')); 80//=> true 81console.log(brackets.isMatch('1.2', '[[:alpha:]].[[:alpha:]]')); 82//=> false 83``` 84 85**Params** 86 87* `string` **{String}**: String to match 88* `pattern` **{String}**: Poxis pattern 89* `options` **{String}** 90* `returns` **{Boolean}** 91 92### [.matcher](index.js#L123) 93 94Takes a POSIX character class pattern and returns a matcher function. The returned function takes the string to match as its only argument. 95 96**Example** 97 98```js 99var brackets = require('expand-brackets'); 100var isMatch = brackets.matcher('[[:lower:]].[[:upper:]]'); 101 102console.log(isMatch('a.a')); 103//=> false 104console.log(isMatch('a.A')); 105//=> true 106``` 107 108**Params** 109 110* `pattern` **{String}**: Poxis pattern 111* `options` **{String}** 112* `returns` **{Boolean}** 113 114### [.makeRe](index.js#L145) 115 116Create a regular expression from the given `pattern`. 117 118**Example** 119 120```js 121var brackets = require('expand-brackets'); 122var re = brackets.makeRe('[[:alpha:]]'); 123console.log(re); 124//=> /^(?:[a-zA-Z])$/ 125``` 126 127**Params** 128 129* `pattern` **{String}**: The pattern to convert to regex. 130* `options` **{Object}** 131* `returns` **{RegExp}** 132 133### [.create](index.js#L187) 134 135Parses the given POSIX character class `pattern` and returns an object with the compiled `output` and optional source `map`. 136 137**Example** 138 139```js 140var brackets = require('expand-brackets'); 141console.log(brackets('[[:alpha:]]')); 142// { options: { source: 'string' }, 143// input: '[[:alpha:]]', 144// state: {}, 145// compilers: 146// { eos: [Function], 147// noop: [Function], 148// bos: [Function], 149// not: [Function], 150// escape: [Function], 151// text: [Function], 152// posix: [Function], 153// bracket: [Function], 154// 'bracket.open': [Function], 155// 'bracket.inner': [Function], 156// 'bracket.literal': [Function], 157// 'bracket.close': [Function] }, 158// output: '[a-zA-Z]', 159// ast: 160// { type: 'root', 161// errors: [], 162// nodes: [ [Object], [Object], [Object] ] }, 163// parsingErrors: [] } 164``` 165 166**Params** 167 168* `pattern` **{String}** 169* `options` **{Object}** 170* `returns` **{Object}** 171 172## Options 173 174### options.sourcemap 175 176Generate a source map for the given pattern. 177 178**Example** 179 180```js 181var res = brackets('[:alpha:]', {sourcemap: true}); 182 183console.log(res.map); 184// { version: 3, 185// sources: [ 'brackets' ], 186// names: [], 187// mappings: 'AAAA,MAAS', 188// sourcesContent: [ '[:alpha:]' ] } 189``` 190 191### POSIX Character classes 192 193The following named POSIX bracket expressions are supported: 194 195* `[:alnum:]`: Alphanumeric characters (`a-zA-Z0-9]`) 196* `[:alpha:]`: Alphabetic characters (`a-zA-Z]`) 197* `[:blank:]`: Space and tab (`[ t]`) 198* `[:digit:]`: Digits (`[0-9]`) 199* `[:lower:]`: Lowercase letters (`[a-z]`) 200* `[:punct:]`: Punctuation and symbols. (`[!"#$%&'()*+, -./:;<=>?@ [\]^_``{|}~]`) 201* `[:upper:]`: Uppercase letters (`[A-Z]`) 202* `[:word:]`: Word characters (letters, numbers and underscores) (`[A-Za-z0-9_]`) 203* `[:xdigit:]`: Hexadecimal digits (`[A-Fa-f0-9]`) 204 205See [posix-character-classes](https://github.com/jonschlinkert/posix-character-classes) for more details. 206 207**Not supported** 208 209* [equivalence classes](https://www.gnu.org/software/gawk/manual/html_node/Bracket-Expressions.html) are not supported 210* [POSIX.2 collating symbols](https://www.gnu.org/software/gawk/manual/html_node/Bracket-Expressions.html) are not supported 211 212## Changelog 213 214### v2.0.0 215 216**Breaking changes** 217 218* The main export now returns the compiled string, instead of the object returned from the compiler 219 220**Added features** 221 222* Adds a `.create` method to do what the main function did before v2.0.0 223 224### v0.2.0 225 226In addition to performance and matching improvements, the v0.2.0 refactor adds complete POSIX character class support, with the exception of equivalence classes and POSIX.2 collating symbols which are not relevant to node.js usage. 227 228**Added features** 229 230* parser is exposed, so that expand-brackets parsers can be used by upstream parsers (like [micromatch](https://github.com/jonschlinkert/micromatch)) 231* compiler is exposed, so that expand-brackets compilers can be used by upstream compilers 232* source maps 233 234**source map example** 235 236```js 237var brackets = require('expand-brackets'); 238var res = brackets('[:alpha:]'); 239console.log(res.map); 240 241{ version: 3, 242 sources: [ 'brackets' ], 243 names: [], 244 mappings: 'AAAA,MAAS', 245 sourcesContent: [ '[:alpha:]' ] } 246``` 247 248## About 249 250### Related projects 251 252* [braces](https://www.npmjs.com/package/braces): Fast, comprehensive, bash-like brace expansion implemented in JavaScript. Complete support for the Bash 4.3 braces… [more](https://github.com/jonschlinkert/braces) | [homepage](https://github.com/jonschlinkert/braces "Fast, comprehensive, bash-like brace expansion implemented in JavaScript. Complete support for the Bash 4.3 braces specification, without sacrificing speed.") 253* [extglob](https://www.npmjs.com/package/extglob): Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob… [more](https://github.com/jonschlinkert/extglob) | [homepage](https://github.com/jonschlinkert/extglob "Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob patterns.") 254* [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 "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.") 255* [nanomatch](https://www.npmjs.com/package/nanomatch): Fast, minimal glob matcher for node.js. Similar to micromatch, minimatch and multimatch, but complete Bash… [more](https://github.com/jonschlinkert/nanomatch) | [homepage](https://github.com/jonschlinkert/nanomatch "Fast, minimal glob matcher for node.js. Similar to micromatch, minimatch and multimatch, but complete Bash 4.3 wildcard support only (no support for exglobs, posix brackets or braces)") 256 257### Contributing 258 259Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 260 261### Contributors 262 263| **Commits** | **Contributor**<br/> | 264| --- | --- | 265| 66 | [jonschlinkert](https://github.com/jonschlinkert) | 266| 2 | [MartinKolarik](https://github.com/MartinKolarik) | 267| 2 | [es128](https://github.com/es128) | 268| 1 | [eush77](https://github.com/eush77) | 269 270### Building docs 271 272_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_ 273 274To generate the readme and API documentation with [verb](https://github.com/verbose/verb): 275 276```sh 277$ npm install -g verb verb-generate-readme && verb 278``` 279 280### Running tests 281 282Install dev dependencies: 283 284```sh 285$ npm install -d && npm test 286``` 287 288### Author 289 290**Jon Schlinkert** 291 292* [github/jonschlinkert](https://github.com/jonschlinkert) 293* [twitter/jonschlinkert](http://twitter.com/jonschlinkert) 294 295### License 296 297Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert). 298Released under the [MIT license](https://github.com/jonschlinkert/expand-brackets/blob/master/LICENSE). 299 300*** 301 302_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on December 12, 2016._