diff options
Diffstat (limited to 'node_modules/fill-range/README.md')
| -rw-r--r--[-rwxr-xr-x] | node_modules/fill-range/README.md | 340 |
1 files changed, 150 insertions, 190 deletions
diff --git a/node_modules/fill-range/README.md b/node_modules/fill-range/README.md index c69694a38..bc1f8a044 100755..100644 --- a/node_modules/fill-range/README.md +++ b/node_modules/fill-range/README.md @@ -1,290 +1,250 @@ -# fill-range [](http://badge.fury.io/js/fill-range) [](https://travis-ci.org/jonschlinkert/fill-range) +# fill-range [](https://www.npmjs.com/package/fill-range) [](https://npmjs.org/package/fill-range) [](https://npmjs.org/package/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. +> Fill in a range of numbers or letters, optionally passing an increment or `step` to use, or create a regex-compatible range with `options.toRegex` -## Install with [npm](npmjs.org) - -```bash -npm i fill-range --save -``` - -<!-- toc --> +## Table of Contents +- [Install](#install) - [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 --> +- [Examples](#examples) +- [Options](#options) + * [options.step](#optionsstep) + * [options.strictRanges](#optionsstrictranges) + * [options.stringify](#optionsstringify) + * [options.toRegex](#optionstoregex) + * [options.transform](#optionstransform) +- [About](#about) -## Usage +_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_ -```js -var range = require('fill-range'); +## Install + +Install with [npm](https://www.npmjs.com/): -range('a', 'e'); -//=> ['a', 'b', 'c', 'd', 'e'] +```sh +$ npm install --save fill-range ``` -**Params** +Install with [yarn](https://yarnpkg.com): -```js -range(start, stop, step, options, fn); +```sh +$ yarn add fill-range ``` - - `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 - +## Usage -**Examples** +Expands numbers and letters, optionally using a `step` as the last argument. _(Numbers may be defined as JavaScript numbers or strings)_. ```js -range(1, 3) -//=> ['1', '2', '3'] - -range('1', '3') -//=> ['1', '2', '3'] +var fill = require('fill-range'); +fill(from, to[, step, options]); -range('0', '-5') -//=> [ '0', '-1', '-2', '-3', '-4', '-5' ] +// examples +console.log(fill('1', '10')); //=> '[ '1', '2', '3', '4', '5', '6', '7', '8', '9', '10' ]' +console.log(fill('1', '10', {toRegex: true})); //=> [1-9]|10 +``` -range(-9, 9, 3) -//=> [ '-9', '-6', '-3', '0', '3', '6', '9' ]) +**Params** -range('-1', '-10', '-2') -//=> [ '-1', '-3', '-5', '-7', '-9' ] +* `from`: **{String|Number}** the number or letter to start with +* `to`: **{String|Number}** the number or letter to end with +* `step`: **{String|Number|Object|Function}** Optionally pass a [step](#optionsstep) to use. +* `options`: **{Object|Function}**: See all available [options](#options) -range('1', '10', '2') -//=> [ '1', '3', '5', '7', '9' ] +## Examples -range('a', 'e') -//=> ['a', 'b', 'c', 'd', 'e'] +By default, an array of values is returned. -range('a', 'e', 2) -//=> ['a', 'c', 'e'] +**Alphabetical ranges** -range('A', 'E', 2) -//=> ['A', 'C', 'E'] +```js +console.log(fill('a', 'e')); //=> ['a', 'b', 'c', 'd', 'e'] +console.log(fill('A', 'E')); //=> [ 'A', 'B', 'C', 'D', 'E' ] ``` -### Invalid ranges +**Numerical ranges** -When an invalid range is passed, `null` is returned. +Numbers can be defined as actual numbers or strings. ```js -range('1.1', '2'); -//=> null - -range('a', '2'); -//=> null - -range(1, 10, 'foo'); -//=> null +console.log(fill(1, 5)); //=> [ 1, 2, 3, 4, 5 ] +console.log(fill('1', '5')); //=> [ 1, 2, 3, 4, 5 ] ``` -If you want errors to be throw, pass `silent: false` on the options: +**Negative ranges** - -### Custom function - -Optionally pass a custom function as the third or fourth argument: +Numbers can be defined as actual numbers or strings. ```js -range('a', 'e', function (val, isNumber, pad, i) { - if (!isNumber) { - return String.fromCharCode(val) + i; - } - return val; -}); -//=> ['a0', 'b1', 'c2', 'd3', 'e4'] +console.log(fill('-5', '-1')); //=> [ '-5', '-4', '-3', '-2', '-1' ] +console.log(fill('-5', '5')); //=> [ '-5', '-4', '-3', '-2', '-1', '0', '1', '2', '3', '4', '5' ] ``` -### 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. +**Steps (increments)** ```js -range('a', 'z', SPECIAL_CHARACTER_HERE); +// numerical ranges with increments +console.log(fill('0', '25', 4)); //=> [ '0', '4', '8', '12', '16', '20', '24' ] +console.log(fill('0', '25', 5)); //=> [ '0', '5', '10', '15', '20', '25' ] +console.log(fill('0', '25', 6)); //=> [ '0', '6', '12', '18', '24' ] + +// alphabetical ranges with increments +console.log(fill('a', 'z', 4)); //=> [ 'a', 'e', 'i', 'm', 'q', 'u', 'y' ] +console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ] +console.log(fill('a', 'z', 6)); //=> [ 'a', 'g', 'm', 's', 'y' ] ``` -**Supported characters** +## Options - - `+`: 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] +### options.step -#### plus +**Type**: `number` (formatted as a string or number) -Character: _(`+`)_ +**Default**: `undefined` -Repeat the first argument the number of times passed on the second argument. +**Description**: The increment to use for the range. Can be used with letters or numbers. -**Examples:** +**Example(s)** ```js -range('a', 3, '+'); -//=> ['a', 'a', 'a'] +// numbers +console.log(fill('1', '10', 2)); //=> [ '1', '3', '5', '7', '9' ] +console.log(fill('1', '10', 3)); //=> [ '1', '4', '7', '10' ] +console.log(fill('1', '10', 4)); //=> [ '1', '5', '9' ] -range('abc', 2, '+'); -//=> ['abc', 'abc'] +// letters +console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ] +console.log(fill('a', 'z', 7)); //=> [ 'a', 'h', 'o', 'v' ] +console.log(fill('a', 'z', 9)); //=> [ 'a', 'j', 's' ] ``` -#### pipe and tilde +### options.strictRanges -Characters: _(`|` and `~`)_ +**Type**: `boolean` -Creates a regex-capable string (either a logical `or` or a character class) from the expanded arguments. +**Default**: `false` -**Examples:** +**Description**: By default, `null` is returned when an invalid range is passed. Enable this option to throw a `RangeError` on invalid ranges. -```js -range('a', 'c', '|'); -//=> ['(a|b|c)' +**Example(s)** -range('a', 'c', '~'); -//=> ['[a-c]' +The following are all invalid: -range('a', 'z', '|5'); -//=> ['(a|f|k|p|u|z)' +```js +fill('1.1', '2'); // decimals not supported in ranges +fill('a', '2'); // incompatible range values +fill(1, 10, 'foo'); // invalid "step" argument ``` -**Automatic separator correction** - -To avoid this error: +### options.stringify -> `Range out of order in character class` +**Type**: `boolean` -Fill-range detects invalid sequences and uses the correct syntax. For example: +**Default**: `undefined` -**invalid** (regex) +**Description**: Cast all returned values to strings. By default, integers are returned as numbers. -If you pass these: +**Example(s)** ```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]'] +console.log(fill(1, 5)); //=> [ 1, 2, 3, 4, 5 ] +console.log(fill(1, 5, {stringify: true})); //=> [ '1', '2', '3', '4', '5' ] ``` -**valid** (regex) +### options.toRegex -fill-range corrects them to this: +**Type**: `boolean` -```js -range('a', 'z', '~5'); -//=> ['(a|f|k|p|u|z)' +**Default**: `undefined` + +**Description**: Create a regex-compatible source string, instead of expanding values to an array. -range('10', '20', '~'); -//=> ['(10-20)' +**Example(s)** + +```js +// alphabetical range +console.log(fill('a', 'e', {toRegex: true})); //=> '[a-e]' +// alphabetical with step +console.log(fill('a', 'z', 3, {toRegex: true})); //=> 'a|d|g|j|m|p|s|v|y' +// numerical range +console.log(fill('1', '100', {toRegex: true})); //=> '[1-9]|[1-9][0-9]|100' +// numerical range with zero padding +console.log(fill('000001', '100000', {toRegex: true})); +//=> '0{5}[1-9]|0{4}[1-9][0-9]|0{3}[1-9][0-9]{2}|0{2}[1-9][0-9]{3}|0[1-9][0-9]{4}|100000' ``` -#### angle bracket +### options.transform -Character: _(`>`)_ +**Type**: `function` -Joins all values in the returned array to a single value. +**Default**: `undefined` -**Examples:** +**Description**: Customize each value in the returned array (or [string](#optionstoRegex)). _(you can also pass this function as the last argument to `fill()`)_. -```js -range('a', 'e', '>'); -//=> ['abcde'] +**Example(s)** -range('5', '8', '>'); -//=> ['5678'] +```js +// increase padding by two +var arr = fill('01', '05', function(val, a, b, step, idx, arr, options) { + return repeat('0', (options.maxLength + 2) - val.length) + val; +}); -range('2', '20', '2>'); -//=> ['2468101214161820'] +console.log(arr); +//=> ['0001', '0002', '0003', '0004', '0005'] ``` +## About -#### question mark +### Related projects -Character: _(`?`)_ +* [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.") +* [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://github.com/jonschlinkert/expand-range) | [homepage](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.") +* [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.") +* [to-regex-range](https://www.npmjs.com/package/to-regex-range): Pass two numbers, get a regex-compatible source string for matching ranges. Validated against more than… [more](https://github.com/jonschlinkert/to-regex-range) | [homepage](https://github.com/jonschlinkert/to-regex-range "Pass two numbers, get a regex-compatible source string for matching ranges. Validated against more than 2.87 million test assertions.") -Uses [randomatic] to generate randomized alpha, numeric, or alpha-numeric patterns based on the provided arguments. +### Contributing -**Examples:** +Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). -_(actual results would obviously be randomized)_ +### Contributors -Generate a 5-character, uppercase, alphabetical string: +| **Commits** | **Contributor** | +| --- | --- | +| 103 | [jonschlinkert](https://github.com/jonschlinkert) | +| 2 | [paulmillr](https://github.com/paulmillr) | +| 1 | [edorivai](https://github.com/edorivai) | +| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) | -```js -range('A', 5, '?'); -//=> ['NSHAK'] -``` - -Generate a 5-digit random number: +### Building docs -```js -range('0', 5, '?'); -//=> ['36583'] -``` +_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ -Generate a 10-character alpha-numeric string: +To generate the readme, run the following command: -```js -range('A0', 10, '?'); -//=> ['5YJD60VQNN'] +```sh +$ npm install -g verbose/verb#dev verb-generate-readme && verb ``` -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 -## Running tests -Install dev dependencies: +Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: -```bash -npm i -d && npm test +```sh +$ npm install && 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 +### Author **Jon Schlinkert** -+ [github/jonschlinkert](https://github.com/jonschlinkert) -+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert) +* [github/jonschlinkert](https://github.com/jonschlinkert) +* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) -## License -Copyright (c) 2014-2015 Jon Schlinkert -Released under the MIT license +### License -*** +Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). +Released under the [MIT License](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 +_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.5.0, on April 23, 2017._
\ No newline at end of file |