README.md
1 # split-string [](https://www.npmjs.com/package/split-string) [](https://npmjs.org/package/split-string) [](https://npmjs.org/package/split-string) [](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._