You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 9.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  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. > Expand POSIX bracket expressions (character classes) in glob patterns.
  3. ## Install
  4. Install with [npm](https://www.npmjs.com/):
  5. ```sh
  6. $ npm install --save expand-brackets
  7. ```
  8. ## Usage
  9. ```js
  10. var brackets = require('expand-brackets');
  11. brackets(string[, options]);
  12. ```
  13. **Params**
  14. The main export is a function that takes the following parameters:
  15. * `pattern` **{String}**: the pattern to convert
  16. * `options` **{Object}**: optionally supply an options object
  17. * `returns` **{String}**: returns a string that can be used to create a regex
  18. **Example**
  19. ```js
  20. console.log(brackets('[![:lower:]]'));
  21. //=> '[^a-z]'
  22. ```
  23. ## API
  24. ### [brackets](index.js#L29)
  25. Parses the given POSIX character class `pattern` and returns a
  26. string that can be used for creating regular expressions for matching.
  27. **Params**
  28. * `pattern` **{String}**
  29. * `options` **{Object}**
  30. * `returns` **{Object}**
  31. ### [.match](index.js#L54)
  32. Takes an array of strings and a POSIX character class pattern, and returns a new array with only the strings that matched the pattern.
  33. **Example**
  34. ```js
  35. var brackets = require('expand-brackets');
  36. console.log(brackets.match(['1', 'a', 'ab'], '[[:alpha:]]'));
  37. //=> ['a']
  38. console.log(brackets.match(['1', 'a', 'ab'], '[[:alpha:]]+'));
  39. //=> ['a', 'ab']
  40. ```
  41. **Params**
  42. * `arr` **{Array}**: Array of strings to match
  43. * `pattern` **{String}**: POSIX character class pattern(s)
  44. * `options` **{Object}**
  45. * `returns` **{Array}**
  46. ### [.isMatch](index.js#L100)
  47. Returns true if the specified `string` matches the given brackets `pattern`.
  48. **Example**
  49. ```js
  50. var brackets = require('expand-brackets');
  51. console.log(brackets.isMatch('a.a', '[[:alpha:]].[[:alpha:]]'));
  52. //=> true
  53. console.log(brackets.isMatch('1.2', '[[:alpha:]].[[:alpha:]]'));
  54. //=> false
  55. ```
  56. **Params**
  57. * `string` **{String}**: String to match
  58. * `pattern` **{String}**: Poxis pattern
  59. * `options` **{String}**
  60. * `returns` **{Boolean}**
  61. ### [.matcher](index.js#L123)
  62. Takes a POSIX character class pattern and returns a matcher function. The returned function takes the string to match as its only argument.
  63. **Example**
  64. ```js
  65. var brackets = require('expand-brackets');
  66. var isMatch = brackets.matcher('[[:lower:]].[[:upper:]]');
  67. console.log(isMatch('a.a'));
  68. //=> false
  69. console.log(isMatch('a.A'));
  70. //=> true
  71. ```
  72. **Params**
  73. * `pattern` **{String}**: Poxis pattern
  74. * `options` **{String}**
  75. * `returns` **{Boolean}**
  76. ### [.makeRe](index.js#L145)
  77. Create a regular expression from the given `pattern`.
  78. **Example**
  79. ```js
  80. var brackets = require('expand-brackets');
  81. var re = brackets.makeRe('[[:alpha:]]');
  82. console.log(re);
  83. //=> /^(?:[a-zA-Z])$/
  84. ```
  85. **Params**
  86. * `pattern` **{String}**: The pattern to convert to regex.
  87. * `options` **{Object}**
  88. * `returns` **{RegExp}**
  89. ### [.create](index.js#L187)
  90. Parses the given POSIX character class `pattern` and returns an object with the compiled `output` and optional source `map`.
  91. **Example**
  92. ```js
  93. var brackets = require('expand-brackets');
  94. console.log(brackets('[[:alpha:]]'));
  95. // { options: { source: 'string' },
  96. // input: '[[:alpha:]]',
  97. // state: {},
  98. // compilers:
  99. // { eos: [Function],
  100. // noop: [Function],
  101. // bos: [Function],
  102. // not: [Function],
  103. // escape: [Function],
  104. // text: [Function],
  105. // posix: [Function],
  106. // bracket: [Function],
  107. // 'bracket.open': [Function],
  108. // 'bracket.inner': [Function],
  109. // 'bracket.literal': [Function],
  110. // 'bracket.close': [Function] },
  111. // output: '[a-zA-Z]',
  112. // ast:
  113. // { type: 'root',
  114. // errors: [],
  115. // nodes: [ [Object], [Object], [Object] ] },
  116. // parsingErrors: [] }
  117. ```
  118. **Params**
  119. * `pattern` **{String}**
  120. * `options` **{Object}**
  121. * `returns` **{Object}**
  122. ## Options
  123. ### options.sourcemap
  124. Generate a source map for the given pattern.
  125. **Example**
  126. ```js
  127. var res = brackets('[:alpha:]', {sourcemap: true});
  128. console.log(res.map);
  129. // { version: 3,
  130. // sources: [ 'brackets' ],
  131. // names: [],
  132. // mappings: 'AAAA,MAAS',
  133. // sourcesContent: [ '[:alpha:]' ] }
  134. ```
  135. ### POSIX Character classes
  136. The following named POSIX bracket expressions are supported:
  137. * `[:alnum:]`: Alphanumeric characters (`a-zA-Z0-9]`)
  138. * `[:alpha:]`: Alphabetic characters (`a-zA-Z]`)
  139. * `[:blank:]`: Space and tab (`[ t]`)
  140. * `[:digit:]`: Digits (`[0-9]`)
  141. * `[:lower:]`: Lowercase letters (`[a-z]`)
  142. * `[:punct:]`: Punctuation and symbols. (`[!"#$%&'()*+, -./:;<=>?@ [\]^_``{|}~]`)
  143. * `[:upper:]`: Uppercase letters (`[A-Z]`)
  144. * `[:word:]`: Word characters (letters, numbers and underscores) (`[A-Za-z0-9_]`)
  145. * `[:xdigit:]`: Hexadecimal digits (`[A-Fa-f0-9]`)
  146. See [posix-character-classes](https://github.com/jonschlinkert/posix-character-classes) for more details.
  147. **Not supported**
  148. * [equivalence classes](https://www.gnu.org/software/gawk/manual/html_node/Bracket-Expressions.html) are not supported
  149. * [POSIX.2 collating symbols](https://www.gnu.org/software/gawk/manual/html_node/Bracket-Expressions.html) are not supported
  150. ## Changelog
  151. ### v2.0.0
  152. **Breaking changes**
  153. * The main export now returns the compiled string, instead of the object returned from the compiler
  154. **Added features**
  155. * Adds a `.create` method to do what the main function did before v2.0.0
  156. ### v0.2.0
  157. In 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.
  158. **Added features**
  159. * parser is exposed, so that expand-brackets parsers can be used by upstream parsers (like [micromatch](https://github.com/jonschlinkert/micromatch))
  160. * compiler is exposed, so that expand-brackets compilers can be used by upstream compilers
  161. * source maps
  162. **source map example**
  163. ```js
  164. var brackets = require('expand-brackets');
  165. var res = brackets('[:alpha:]');
  166. console.log(res.map);
  167. { version: 3,
  168. sources: [ 'brackets' ],
  169. names: [],
  170. mappings: 'AAAA,MAAS',
  171. sourcesContent: [ '[:alpha:]' ] }
  172. ```
  173. ## About
  174. ### Related projects
  175. * [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.")
  176. * [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.")
  177. * [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.")
  178. * [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)")
  179. ### Contributing
  180. Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
  181. ### Contributors
  182. | **Commits** | **Contributor**<br/> |
  183. | --- | --- |
  184. | 66 | [jonschlinkert](https://github.com/jonschlinkert) |
  185. | 2 | [MartinKolarik](https://github.com/MartinKolarik) |
  186. | 2 | [es128](https://github.com/es128) |
  187. | 1 | [eush77](https://github.com/eush77) |
  188. ### Building docs
  189. _(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).)_
  190. To generate the readme and API documentation with [verb](https://github.com/verbose/verb):
  191. ```sh
  192. $ npm install -g verb verb-generate-readme && verb
  193. ```
  194. ### Running tests
  195. Install dev dependencies:
  196. ```sh
  197. $ npm install -d && npm test
  198. ```
  199. ### Author
  200. **Jon Schlinkert**
  201. * [github/jonschlinkert](https://github.com/jonschlinkert)
  202. * [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
  203. ### License
  204. Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
  205. Released under the [MIT license](https://github.com/jonschlinkert/expand-brackets/blob/master/LICENSE).
  206. ***
  207. _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on December 12, 2016._