diff options
Diffstat (limited to 'node_modules/fill-range/README.md')
| -rwxr-xr-x | node_modules/fill-range/README.md | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/node_modules/fill-range/README.md b/node_modules/fill-range/README.md new file mode 100755 index 000000000..c69694a38 --- /dev/null +++ b/node_modules/fill-range/README.md @@ -0,0 +1,290 @@ +# fill-range [](http://badge.fury.io/js/fill-range) [](https://travis-ci.org/jonschlinkert/fill-range) + +> Fill in a range of numbers or letters, optionally passing an increment or multiplier to use. + +## Install with [npm](npmjs.org) + +```bash +npm i fill-range --save +``` + +<!-- toc --> + +- [Usage](#usage) + * [Invalid ranges](#invalid-ranges) + * [Custom function](#custom-function) + * [Special characters](#special-characters) + + [plus](#plus) + + [pipe and tilde](#pipe-and-tilde) + + [angle bracket](#angle-bracket) + + [question mark](#question-mark) +- [Other useful libs](#other-useful-libs) +- [Running tests](#running-tests) +- [Contributing](#contributing) +- [Author](#author) +- [License](#license) + +_(Table of contents generated by [verb])_ + +<!-- tocstop --> + +## Usage + +```js +var range = require('fill-range'); + +range('a', 'e'); +//=> ['a', 'b', 'c', 'd', 'e'] +``` + +**Params** + +```js +range(start, stop, step, options, fn); +``` + + - `start`: **{String|Number}** the number or letter to start with + - `end`: **{String|Number}** the number or letter to end with + - `step`: **{String|Number}** optionally pass the step to use. works for letters or numbers. + - `options`: **{Object}**: + + `makeRe`: return a regex-compatible string (still returned as an array for consistency) + + `step`: pass the step on the options as an alternative to passing it as an argument + + `silent`: `true` by default, set to false to throw errors for invalid ranges. + - `fn`: **{Function}** optionally [pass a function](#custom-function) to modify each character + + +**Examples** + +```js +range(1, 3) +//=> ['1', '2', '3'] + +range('1', '3') +//=> ['1', '2', '3'] + +range('0', '-5') +//=> [ '0', '-1', '-2', '-3', '-4', '-5' ] + +range(-9, 9, 3) +//=> [ '-9', '-6', '-3', '0', '3', '6', '9' ]) + +range('-1', '-10', '-2') +//=> [ '-1', '-3', '-5', '-7', '-9' ] + +range('1', '10', '2') +//=> [ '1', '3', '5', '7', '9' ] + +range('a', 'e') +//=> ['a', 'b', 'c', 'd', 'e'] + +range('a', 'e', 2) +//=> ['a', 'c', 'e'] + +range('A', 'E', 2) +//=> ['A', 'C', 'E'] +``` + +### Invalid ranges + +When an invalid range is passed, `null` is returned. + +```js +range('1.1', '2'); +//=> null + +range('a', '2'); +//=> null + +range(1, 10, 'foo'); +//=> null +``` + +If you want errors to be throw, pass `silent: false` on the options: + + +### Custom function + +Optionally pass a custom function as the third or fourth argument: + +```js +range('a', 'e', function (val, isNumber, pad, i) { + if (!isNumber) { + return String.fromCharCode(val) + i; + } + return val; +}); +//=> ['a0', 'b1', 'c2', 'd3', 'e4'] +``` + +### Special characters + +A special character may be passed as the third arg instead of a step increment. These characters can be pretty useful for brace expansion, creating file paths, test fixtures and similar use case. + +```js +range('a', 'z', SPECIAL_CHARACTER_HERE); +``` + +**Supported characters** + + - `+`: repeat the given string `n` times + - `|`: create a regex-ready string, instead of an array + - `>`: join values to single array element + - `?`: randomize the given pattern using [randomatic] + +#### plus + +Character: _(`+`)_ + +Repeat the first argument the number of times passed on the second argument. + +**Examples:** + +```js +range('a', 3, '+'); +//=> ['a', 'a', 'a'] + +range('abc', 2, '+'); +//=> ['abc', 'abc'] +``` + +#### pipe and tilde + +Characters: _(`|` and `~`)_ + +Creates a regex-capable string (either a logical `or` or a character class) from the expanded arguments. + +**Examples:** + +```js +range('a', 'c', '|'); +//=> ['(a|b|c)' + +range('a', 'c', '~'); +//=> ['[a-c]' + +range('a', 'z', '|5'); +//=> ['(a|f|k|p|u|z)' +``` + +**Automatic separator correction** + +To avoid this error: + +> `Range out of order in character class` + +Fill-range detects invalid sequences and uses the correct syntax. For example: + +**invalid** (regex) + +If you pass these: + +```js +range('a', 'z', '~5'); +// which would result in this +//=> ['[a-f-k-p-u-z]'] + +range('10', '20', '~'); +// which would result in this +//=> ['[10-20]'] +``` + +**valid** (regex) + +fill-range corrects them to this: + +```js +range('a', 'z', '~5'); +//=> ['(a|f|k|p|u|z)' + +range('10', '20', '~'); +//=> ['(10-20)' +``` + +#### angle bracket + +Character: _(`>`)_ + +Joins all values in the returned array to a single value. + +**Examples:** + +```js +range('a', 'e', '>'); +//=> ['abcde'] + +range('5', '8', '>'); +//=> ['5678'] + +range('2', '20', '2>'); +//=> ['2468101214161820'] +``` + + +#### question mark + +Character: _(`?`)_ + +Uses [randomatic] to generate randomized alpha, numeric, or alpha-numeric patterns based on the provided arguments. + +**Examples:** + +_(actual results would obviously be randomized)_ + +Generate a 5-character, uppercase, alphabetical string: + +```js +range('A', 5, '?'); +//=> ['NSHAK'] +``` + +Generate a 5-digit random number: + +```js +range('0', 5, '?'); +//=> ['36583'] +``` + +Generate a 10-character alpha-numeric string: + +```js +range('A0', 10, '?'); +//=> ['5YJD60VQNN'] +``` + +See the [randomatic] repo for all available options and or to create issues or feature requests related to randomization. + +## Other useful libs + * [micromatch](https://github.com/jonschlinkert/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. Just use `micromatch.isMatch()` instead of `minimatch()`, or use `micromatch()` instead of `multimatch()`. + * [expand-range](https://github.com/jonschlinkert/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See the benchmarks. Used by micromatch. + * [braces](https://github.com/jonschlinkert/braces): Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification. + * [is-glob](https://github.com/jonschlinkert/is-glob): Returns `true` if the given string looks like a glob pattern. + +## Running tests +Install dev dependencies: + +```bash +npm i -d && npm test +``` + +## Contributing +Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/fill-range/issues) + +## Author + +**Jon Schlinkert** + ++ [github/jonschlinkert](https://github.com/jonschlinkert) ++ [twitter/jonschlinkert](http://twitter.com/jonschlinkert) + +## License +Copyright (c) 2014-2015 Jon Schlinkert +Released under the MIT license + +*** + +_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on April 07, 2015._ + +[randomatic]: https://github.com/jonschlinkert/randomatic +[expand-range]: https://github.com/jonschlinkert/expand-range +[micromatch]: https://github.com/jonschlinkert/micromatch +[braces]: https://github.com/jonschlinkert/braces
\ No newline at end of file |