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

   1 # fill-range [![NPM version](https://badge.fury.io/js/fill-range.svg)](http://badge.fury.io/js/fill-range)  [![Build Status](https://travis-ci.org/jonschlinkert/fill-range.svg)](https://travis-ci.org/jonschlinkert/fill-range)
   2
   3 > Fill in a range of numbers or letters, optionally passing an increment or multiplier to use.
   4
   5 ## Install with [npm](npmjs.org)
   6
   7 ```bash
   8 npm i fill-range --save
   9 ```
  10
  11 <!-- toc -->
  12
  13 - [Usage](#usage)
  14   * [Invalid ranges](#invalid-ranges)
  15   * [Custom function](#custom-function)
  16   * [Special characters](#special-characters)
  17     + [plus](#plus)
  18     + [pipe and tilde](#pipe-and-tilde)
  19     + [angle bracket](#angle-bracket)
  20     + [question mark](#question-mark)
  21 - [Other useful libs](#other-useful-libs)
  22 - [Running tests](#running-tests)
  23 - [Contributing](#contributing)
  24 - [Author](#author)
  25 - [License](#license)
  26
  27 _(Table of contents generated by [verb])_
  28
  29 <!-- tocstop -->
  30
  31 ## Usage
  32
  33 ```js
  34 var range = require('fill-range');
  35
  36 range('a', 'e');
  37 //=> ['a', 'b', 'c', 'd', 'e']
  38 ```
  39
  40 **Params**
  41
  42 ```js
  43 range(start, stop, step, options, fn);
  44 ```
  45
  46  - `start`: **{String|Number}** the number or letter to start with
  47  - `end`: **{String|Number}** the number or letter to end with
  48  - `step`: **{String|Number}** optionally pass the step to use. works for letters or numbers.
  49  - `options`: **{Object}**:
  50     + `makeRe`: return a regex-compatible string (still returned as an array for consistency)
  51     + `step`: pass the step on the options as an alternative to passing it as an argument
  52     + `silent`: `true` by default, set to false to throw errors for invalid ranges.
  53  - `fn`: **{Function}** optionally [pass a function](#custom-function) to modify each character
  54
  55
  56 **Examples**
  57
  58 ```js
  59 range(1, 3)
  60 //=> ['1', '2', '3']
  61
  62 range('1', '3')
  63 //=> ['1', '2', '3']
  64
  65 range('0', '-5')
  66 //=> [ '0', '-1', '-2', '-3', '-4', '-5' ]
  67
  68 range(-9, 9, 3)
  69 //=> [ '-9', '-6', '-3', '0', '3', '6', '9' ])
  70
  71 range('-1', '-10', '-2')
  72 //=> [ '-1', '-3', '-5', '-7', '-9' ]
  73
  74 range('1', '10', '2')
  75 //=> [ '1', '3', '5', '7', '9' ]
  76
  77 range('a', 'e')
  78 //=> ['a', 'b', 'c', 'd', 'e']
  79
  80 range('a', 'e', 2)
  81 //=> ['a', 'c', 'e']
  82
  83 range('A', 'E', 2)
  84 //=> ['A', 'C', 'E']
  85 ```
  86
  87 ### Invalid ranges
  88
  89 When an invalid range is passed, `null` is returned.
  90
  91 ```js
  92 range('1.1', '2');
  93 //=> null
  94
  95 range('a', '2');
  96 //=> null
  97
  98 range(1, 10, 'foo');
  99 //=> null
 100 ```
 101
 102 If you want errors to be throw, pass `silent: false` on the options:
 103
 104
 105 ### Custom function
 106
 107 Optionally pass a custom function as the third or fourth argument:
 108
 109 ```js
 110 range('a', 'e', function (val, isNumber, pad, i) {
 111   if (!isNumber) {
 112     return String.fromCharCode(val) + i;
 113   }
 114   return val;
 115 });
 116 //=> ['a0', 'b1', 'c2', 'd3', 'e4']
 117 ```
 118
 119 ### Special characters
 120
 121 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.
 122
 123 ```js
 124 range('a', 'z', SPECIAL_CHARACTER_HERE);
 125 ```
 126
 127 **Supported characters**
 128
 129  - `+`: repeat the given string `n` times
 130  - `|`: create a regex-ready string, instead of an array
 131  - `>`: join values to single array element
 132  - `?`: randomize the given pattern using [randomatic]
 133
 134 #### plus
 135
 136 Character: _(`+`)_
 137
 138 Repeat the first argument the number of times passed on the second argument.
 139
 140 **Examples:**
 141
 142 ```js
 143 range('a', 3, '+');
 144 //=> ['a', 'a', 'a']
 145
 146 range('abc', 2, '+');
 147 //=> ['abc', 'abc']
 148 ```
 149
 150 #### pipe and tilde
 151
 152 Characters: _(`|` and `~`)_
 153
 154 Creates a regex-capable string (either a logical `or` or a character class) from the expanded arguments.
 155
 156 **Examples:**
 157
 158 ```js
 159 range('a', 'c', '|');
 160 //=> ['(a|b|c)'
 161
 162 range('a', 'c', '~');
 163 //=> ['[a-c]'
 164
 165 range('a', 'z', '|5');
 166 //=> ['(a|f|k|p|u|z)'
 167 ```
 168
 169 **Automatic separator correction**
 170
 171 To avoid this error:
 172
 173 > `Range out of order in character class`
 174
 175 Fill-range detects invalid sequences and uses the correct syntax. For example:
 176
 177 **invalid** (regex)
 178
 179 If you pass these:
 180
 181 ```js
 182 range('a', 'z', '~5');
 183 // which would result in this
 184 //=> ['[a-f-k-p-u-z]']
 185
 186 range('10', '20', '~');
 187 // which would result in this
 188 //=> ['[10-20]']
 189 ```
 190
 191 **valid** (regex)
 192
 193 fill-range corrects them to this:
 194
 195 ```js
 196 range('a', 'z', '~5');
 197 //=> ['(a|f|k|p|u|z)'
 198
 199 range('10', '20', '~');
 200 //=> ['(10-20)'
 201 ```
 202
 203 #### angle bracket
 204
 205 Character: _(`>`)_
 206
 207 Joins all values in the returned array to a single value.
 208
 209 **Examples:**
 210
 211 ```js
 212 range('a', 'e', '>');
 213 //=> ['abcde']
 214
 215 range('5', '8', '>');
 216 //=> ['5678']
 217
 218 range('2', '20', '2>');
 219 //=> ['2468101214161820']
 220 ```
 221
 222
 223 #### question mark
 224
 225 Character: _(`?`)_
 226
 227 Uses [randomatic] to generate randomized alpha, numeric, or alpha-numeric patterns based on the provided arguments.
 228
 229 **Examples:**
 230
 231 _(actual results would obviously be randomized)_
 232
 233 Generate a 5-character, uppercase, alphabetical string:
 234
 235 ```js
 236 range('A', 5, '?');
 237 //=> ['NSHAK']
 238 ```
 239
 240 Generate a 5-digit random number:
 241
 242 ```js
 243 range('0', 5, '?');
 244 //=> ['36583']
 245 ```
 246
 247 Generate a 10-character alpha-numeric string:
 248
 249 ```js
 250 range('A0', 10, '?');
 251 //=> ['5YJD60VQNN']
 252 ```
 253
 254 See the [randomatic] repo for all available options and or to create issues or feature requests related to randomization.
 255
 256 ## Other useful libs
 257  * [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()`.
 258  * [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.
 259  * [braces](https://github.com/jonschlinkert/braces): Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification.
 260  * [is-glob](https://github.com/jonschlinkert/is-glob): Returns `true` if the given string looks like a glob pattern.
 261
 262 ## Running tests
 263 Install dev dependencies:
 264
 265 ```bash
 266 npm i -d && npm test
 267 ```
 268
 269 ## Contributing
 270 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/fill-range/issues)
 271
 272 ## Author
 273
 274 **Jon Schlinkert**
 275
 276 + [github/jonschlinkert](https://github.com/jonschlinkert)
 277 + [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
 278
 279 ## License
 280 Copyright (c) 2014-2015 Jon Schlinkert
 281 Released under the MIT license
 282
 283 ***
 284
 285 _This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on April 07, 2015._
 286
 287 [randomatic]: https://github.com/jonschlinkert/randomatic
 288 [expand-range]: https://github.com/jonschlinkert/expand-range
 289 [micromatch]: https://github.com/jonschlinkert/micromatch
 290 [braces]: https://github.com/jonschlinkert/braces