.config/coc/extensions/node_modules/coc-prettier/node_modules/split-string/README.md

   1 # split-string [![NPM version](https://img.shields.io/npm/v/split-string.svg?style=flat)](https://www.npmjs.com/package/split-string) [![NPM monthly downloads](https://img.shields.io/npm/dm/split-string.svg?style=flat)](https://npmjs.org/package/split-string) [![NPM total downloads](https://img.shields.io/npm/dt/split-string.svg?style=flat)](https://npmjs.org/package/split-string) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/split-string.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/split-string)
   2
   3 > Split a string on a character except when the character is escaped.
   4
   5 Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
   6
   7 ## Install
   8
   9 Install with [npm](https://www.npmjs.com/):
  10
  11 ```sh
  12 $ npm install --save split-string
  13 ```
  14
  15 <!-- section: Why use this? -->
  16
  17 <details>
  18 <summary><strong>Why use this?</strong></summary>
  19
  20 <br>
  21
  22 Although it's easy to split on a string:
  23
  24 ```js
  25 console.log('a.b.c'.split('.'));
  26 //=> ['a', 'b', 'c']
  27 ```
  28
  29 It's more challenging to split a string whilst respecting escaped or quoted characters.
  30
  31 **Bad**
  32
  33 ```js
  34 console.log('a\\.b.c'.split('.'));
  35 //=> ['a\\', 'b', 'c']
  36
  37 console.log('"a.b.c".d'.split('.'));
  38 //=> ['"a', 'b', 'c"', 'd']
  39 ```
  40
  41 **Good**
  42
  43 ```js
  44 var split = require('split-string');
  45 console.log(split('a\\.b.c'));
  46 //=> ['a.b', 'c']
  47
  48 console.log(split('"a.b.c".d'));
  49 //=> ['a.b.c', 'd']
  50 ```
  51
  52 See the [options](#options) to learn how to choose the separator or retain quotes or escaping.
  53
  54 <br>
  55
  56 </details>
  57
  58 ## Usage
  59
  60 ```js
  61 var split = require('split-string');
  62
  63 split('a.b.c');
  64 //=> ['a', 'b', 'c']
  65
  66 // respects escaped characters
  67 split('a.b.c\\.d');
  68 //=> ['a', 'b', 'c.d']
  69
  70 // respects double-quoted strings
  71 split('a."b.c.d".e');
  72 //=> ['a', 'b.c.d', 'e']
  73 ```
  74
  75 **Brackets**
  76
  77 Also respects brackets [unless disabled](#optionsbrackets):
  78
  79 ```js
  80 split('a (b c d) e', ' ');
  81 //=> ['a', '(b c d)', 'e']
  82 ```
  83
  84 ## Options
  85
  86 ### options.brackets
  87
  88 **Type**: `object|boolean`
  89
  90 **Default**: `undefined`
  91
  92 **Description**
  93
  94 If enabled, split-string will not split inside brackets. The following brackets types are supported when `options.brackets` is `true`,
  95
  96 ```js
  97 {
  98   '<': '>',
  99   '(': ')',
 100   '[': ']',
 101   '{': '}'
 102 }
 103 ```
 104
 105 Or, if object of brackets must be passed, each property on the object must be a bracket type, where the property key is the opening delimiter and property value is the closing delimiter.
 106
 107 **Examples**
 108
 109 ```js
 110 // no bracket support by default
 111 split('a.{b.c}');
 112 //=> [ 'a', '{b', 'c}' ]
 113
 114 // support all basic bracket types: "<>{}[]()"
 115 split('a.{b.c}', {brackets: true});
 116 //=> [ 'a', '{b.c}' ]
 117
 118 // also supports nested brackets
 119 split('a.{b.{c.d}.e}.f', {brackets: true});
 120 //=> [ 'a', '{b.{c.d}.e}', 'f' ]
 121
 122 // support only the specified brackets
 123 split('[a.b].(c.d)', {brackets: {'[': ']'}});
 124 //=> [ '[a.b]', '(c', 'd)' ]
 125 ```
 126
 127 ### options.sep
 128
 129 **Type**: `string`
 130
 131 **Default**: `.`
 132
 133 The separator/character to split on.
 134
 135 **Example**
 136
 137 ```js
 138 split('a.b,c', {sep: ','});
 139 //=> ['a.b', 'c']
 140
 141 // you can also pass the separator as string as the last argument
 142 split('a.b,c', ',');
 143 //=> ['a.b', 'c']
 144 ```
 145
 146 ### options.keepEscaping
 147
 148 **Type**: `boolean`
 149
 150 **Default**: `undefined`
 151
 152 Keep backslashes in the result.
 153
 154 **Example**
 155
 156 ```js
 157 split('a.b\\.c');
 158 //=> ['a', 'b.c']
 159
 160 split('a.b.\\c', {keepEscaping: true});
 161 //=> ['a', 'b\.c']
 162 ```
 163
 164 ### options.keepQuotes
 165
 166 **Type**: `boolean`
 167
 168 **Default**: `undefined`
 169
 170 Keep single- or double-quotes in the result.
 171
 172 **Example**
 173
 174 ```js
 175 split('a."b.c.d".e');
 176 //=> ['a', 'b.c.d', 'e']
 177
 178 split('a."b.c.d".e', {keepQuotes: true});
 179 //=> ['a', '"b.c.d"', 'e']
 180
 181 split('a.\'b.c.d\'.e', {keepQuotes: true});
 182 //=> ['a', '\'b.c.d\'', 'e']
 183 ```
 184
 185 ### options.keepDoubleQuotes
 186
 187 **Type**: `boolean`
 188
 189 **Default**: `undefined`
 190
 191 Keep double-quotes in the result.
 192
 193 **Example**
 194
 195 ```js
 196 split('a."b.c.d".e');
 197 //=> ['a', 'b.c.d', 'e']
 198
 199 split('a."b.c.d".e', {keepDoubleQuotes: true});
 200 //=> ['a', '"b.c.d"', 'e']
 201 ```
 202
 203 ### options.keepSingleQuotes
 204
 205 **Type**: `boolean`
 206
 207 **Default**: `undefined`
 208
 209 Keep single-quotes in the result.
 210
 211 **Example**
 212
 213 ```js
 214 split('a.\'b.c.d\'.e');
 215 //=> ['a', 'b.c.d', 'e']
 216
 217 split('a.\'b.c.d\'.e', {keepSingleQuotes: true});
 218 //=> ['a', '\'b.c.d\'', 'e']
 219 ```
 220
 221 ## Customizer
 222
 223 **Type**: `function`
 224
 225 **Default**: `undefined`
 226
 227 Pass a function as the last argument to customize how tokens are added to the array.
 228
 229 **Example**
 230
 231 ```js
 232 var arr = split('a.b', function(tok) {
 233   if (tok.arr[tok.arr.length - 1] === 'a') {
 234     tok.split = false;
 235   }
 236 });
 237 console.log(arr);
 238 //=> ['a.b']
 239 ```
 240
 241 **Properties**
 242
 243 The `tok` object has the following properties:
 244
 245 * `tok.val` (string) The current value about to be pushed onto the result array
 246 * `tok.idx` (number) the current index in the string
 247 * `tok.str` (string) the entire string
 248 * `tok.arr` (array) the result array
 249
 250 ## Release history
 251
 252 ### v3.0.0 - 2017-06-17
 253
 254 **Added**
 255
 256 * adds support for brackets
 257
 258 ## About
 259
 260 <details>
 261 <summary><strong>Contributing</strong></summary>
 262
 263 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 264
 265 </details>
 266
 267 <details>
 268 <summary><strong>Running Tests</strong></summary>
 269
 270 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:
 271
 272 ```sh
 273 $ npm install && npm test
 274 ```
 275
 276 </details>
 277
 278 <details>
 279 <summary><strong>Building docs</strong></summary>
 280
 281 _(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.)_
 282
 283 To generate the readme, run the following command:
 284
 285 ```sh
 286 $ npm install -g verbose/verb#dev verb-generate-readme && verb
 287 ```
 288
 289 </details>
 290
 291 ### Related projects
 292
 293 You might also be interested in these projects:
 294
 295 * [deromanize](https://www.npmjs.com/package/deromanize): Convert roman numerals to arabic numbers (useful for books, outlines, documentation, slide decks, etc) | [homepage](https://github.com/jonschlinkert/deromanize "Convert roman numerals to arabic numbers (useful for books, outlines, documentation, slide decks, etc)")
 296 * [randomatic](https://www.npmjs.com/package/randomatic): Generate randomized strings of a specified length using simple character sequences. The original generate-password. | [homepage](https://github.com/jonschlinkert/randomatic "Generate randomized strings of a specified length using simple character sequences. The original generate-password.")
 297 * [repeat-string](https://www.npmjs.com/package/repeat-string): Repeat the given string n times. Fastest implementation for repeating a string. | [homepage](https://github.com/jonschlinkert/repeat-string "Repeat the given string n times. Fastest implementation for repeating a string.")
 298 * [romanize](https://www.npmjs.com/package/romanize): Convert numbers to roman numerals (useful for books, outlines, documentation, slide decks, etc) | [homepage](https://github.com/jonschlinkert/romanize "Convert numbers to roman numerals (useful for books, outlines, documentation, slide decks, etc)")
 299
 300 ### Contributors
 301
 302 | **Commits** | **Contributor** |
 303 | --- | --- |
 304 | 28 | [jonschlinkert](https://github.com/jonschlinkert) |
 305 | 9 | [doowb](https://github.com/doowb) |
 306
 307 ### Author
 308
 309 **Jon Schlinkert**
 310
 311 * [github/jonschlinkert](https://github.com/jonschlinkert)
 312 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
 313
 314 ### License
 315
 316 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
 317 Released under the [MIT License](LICENSE).
 318
 319 ***
 320
 321 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on November 19, 2017._