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 | > Easy way to split a string on a given character unless it's quoted or 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 | ## Usage
|
16 |
|
17 | ```js
|
18 | const split = require('split-string');
|
19 |
|
20 | console.log(split('a.b.c'));
|
21 | //=> ['a', 'b', 'c']
|
22 |
|
23 | // respects escaped characters
|
24 | console.log(split('a.b.c\\.d'));
|
25 | //=> ['a', 'b', 'c.d']
|
26 |
|
27 | // respects double-quoted strings
|
28 | console.log(split('a."b.c.d".e'));
|
29 | //=> ['a', '"b.c.d"', 'e']
|
30 | ```
|
31 |
|
32 | ## Options
|
33 |
|
34 | ### options.quotes
|
35 |
|
36 | **Type**: `Array|Boolean`
|
37 |
|
38 | **Default**: `[]`
|
39 |
|
40 | **Description**
|
41 |
|
42 | Tell split-string not to split inside any of the quote characters specified on the quotes option. Each character signifies both the "opening" and "closing" character to use.
|
43 |
|
44 | ```js
|
45 | // default behavior
|
46 | console.log(split('a.b."c.d.e.f.g".h.i'));
|
47 | //=> [ 'a', 'b', '"c', 'd', 'e', 'f', 'g"', 'h', 'i' ]
|
48 |
|
49 | // with quotes
|
50 | console.log(split('a.b."c.d.e.f.g".h.i', { quotes: ['"'] }));
|
51 | //=> [ 'a', 'b', '"c.d.e.f.g"', 'h', 'i' ]
|
52 |
|
53 | // escaped quotes will be ignored
|
54 | console.log(split('a.b.\\"c.d."e.f.g".h.i', { quotes: ['"'] }));
|
55 | //=> [ 'a', 'b', '"c', 'd', '"e.f.g"', 'h', 'i' ]
|
56 |
|
57 | // example of how to exclude non-escaped quotes from the result
|
58 | let keep = (value, state) => {
|
59 | return value !== '\\' && (value !== '"' || state.prev() === '\\');
|
60 | };
|
61 | console.log(split('a.b.\\"c.d."e.f.g".h.i', { quotes: ['"'], keep }));
|
62 | //=> [ 'a', 'b', '"c', 'd', 'e.f.g', 'h', 'i' ]
|
63 | ```
|
64 |
|
65 | ## Options
|
66 |
|
67 | ### options.brackets
|
68 |
|
69 | **Type**: `Object|Boolean`
|
70 |
|
71 | **Default**: `{}`
|
72 |
|
73 | **Description**
|
74 |
|
75 | By default, no special significance is given to bracket-like characters (such as square brackets, curly braces, angle brackets, and so on).
|
76 |
|
77 | ```js
|
78 | // default behavior
|
79 | console.log(split('a.{b.c}.{d.e}'));
|
80 | //=> [ 'a', '{b', 'c}', '{d', 'e}' ]
|
81 | ```
|
82 |
|
83 | When `options.brackets` is `true`, the following brackets types are supported:
|
84 |
|
85 | ```js
|
86 | {
|
87 | '<': '>',
|
88 | '(': ')',
|
89 | '[': ']',
|
90 | '{': '}'
|
91 | }
|
92 | ```
|
93 |
|
94 | For example:
|
95 |
|
96 | ```js
|
97 | console.log(split('a.{b.c}.{d.e}', { brackets: true }));
|
98 | //=> [ 'a', '{b.c}', '{d.e}' ]
|
99 | ```
|
100 |
|
101 | Alternatively, an object of brackets may be passed, where each key is the _opening bracket_ and each value is the corresponding _closing bracket_. Note that the key and value **must be different characters**. If you want to use the same character for both open and close, use the [quotes option](#optionsquotes).
|
102 |
|
103 | **Examples**
|
104 |
|
105 | ```js
|
106 | // no bracket support by default
|
107 | console.log(split('a.{b.c}.[d.e].f'));
|
108 | //=> [ 'a', '{b', 'c}', '[d', 'e]', 'f' ]
|
109 |
|
110 | // tell split-string not to split inside curly braces
|
111 | console.log(split('a.{b.c}.[d.e].f', { brackets: { '{': '}' }}));
|
112 | //=> [ 'a', '{b.c}', '[d', 'e]', 'f' ]
|
113 |
|
114 | // tell split-string not to split inside any of these types: "<>{}[]()"
|
115 | console.log(split('a.{b.c}.[d.e].f', { brackets: true }));
|
116 | //=> [ 'a', '{b.c}', '[d.e]', 'f' ]
|
117 |
|
118 | // ...nested brackets are also supported
|
119 | console.log(split('a.{b.{c.d}.e}.f', { brackets: true }));
|
120 | //=> [ 'a', '{b.{c.d}.e}', 'f' ]
|
121 |
|
122 | // tell split-string not to split inside the given custom types
|
123 | console.log(split('«a.b».⟨c.d⟩.[e.f]', { brackets: { '«': '»', '⟨': '⟩' } }));
|
124 | //=> [ '«a.b»', '⟨c.d⟩', '[e', 'f]' ]
|
125 | ```
|
126 |
|
127 | ### options.keep
|
128 |
|
129 | **Type**: `function`
|
130 |
|
131 | **Default**: Function that returns true if the character is not `\\`.
|
132 |
|
133 | Function that returns true when a character should be retained in the result.
|
134 |
|
135 | **Example**
|
136 |
|
137 | ```js
|
138 | console.log(split('a.b\\.c')); //=> ['a', 'b.c']
|
139 |
|
140 | // keep all characters
|
141 | console.log(split('a.b.\\c', { keep: () => true })); //=> ['a', 'b\.c']
|
142 | ```
|
143 |
|
144 | ### options.separator
|
145 |
|
146 | **Type**: `string`
|
147 |
|
148 | **Default**: `.`
|
149 |
|
150 | The character to split on.
|
151 |
|
152 | **Example**
|
153 |
|
154 | ```js
|
155 | console.log(split('a.b,c', { separator: ',' })); //=> ['a.b', 'c']
|
156 | ```
|
157 |
|
158 | ## Split function
|
159 |
|
160 | Optionally pass a function as the last argument to tell split-string whether or not to split when the specified separator is encountered.
|
161 |
|
162 | **Example**
|
163 |
|
164 | ```js
|
165 | // only split on "." when the "previous" character is "a"
|
166 | console.log(split('a.b.c.a.d.e', state => state.prev() === 'a'));
|
167 | //=> [ 'a', 'b.c.a', 'd.e' ]
|
168 | ```
|
169 |
|
170 | The `state` object exposes the following properties:
|
171 |
|
172 | * `input` - (String) The un-modified, user-defined input string
|
173 | * `separator` - (String) the specified separator to split on.
|
174 | * `index` - (Number) The current cursor position
|
175 | * `value` - (String) The character at the current index
|
176 | * `bos` - (Function) Returns true if position is at the beginning-of-string
|
177 | * `eos` - (Function) Returns true if position is at the end-of-string
|
178 | * `prev` - (Function) Returns the previously scanned character
|
179 | * `next` - (Function) Returns the next character after the current position
|
180 | * `block` - (Object) The "current" AST node.
|
181 | * `stack` - (Array) AST nodes
|
182 |
|
183 | ## About
|
184 |
|
185 | <details>
|
186 | <summary><strong>Contributing</strong></summary>
|
187 |
|
188 | Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
|
189 |
|
190 | </details>
|
191 |
|
192 | <details>
|
193 | <summary><strong>Running Tests</strong></summary>
|
194 |
|
195 | 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:
|
196 |
|
197 | ```sh
|
198 | $ npm install && npm test
|
199 | ```
|
200 |
|
201 | </details>
|
202 |
|
203 | <details>
|
204 | <summary><strong>Building docs</strong></summary>
|
205 |
|
206 | _(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.)_
|
207 |
|
208 | To generate the readme, run the following command:
|
209 |
|
210 | ```sh
|
211 | $ npm install -g verbose/verb#dev verb-generate-readme && verb
|
212 | ```
|
213 |
|
214 | </details>
|
215 |
|
216 | ### Related projects
|
217 |
|
218 | You might also be interested in these projects:
|
219 |
|
220 | * [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)")
|
221 | * [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.")
|
222 | * [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.")
|
223 | * [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)")
|
224 |
|
225 | ### Contributors
|
226 |
|
227 | | **Commits** | **Contributor** |
|
228 | | --- | --- |
|
229 | | 56 | [jonschlinkert](https://github.com/jonschlinkert) |
|
230 | | 12 | [doowb](https://github.com/doowb) |
|
231 | | 6 | [Ovyerus](https://github.com/Ovyerus) |
|
232 | | 1 | [silverwind](https://github.com/silverwind) |
|
233 |
|
234 | ### Author
|
235 |
|
236 | **Jon Schlinkert**
|
237 |
|
238 | * [GitHub Profile](https://github.com/jonschlinkert)
|
239 | * [Twitter Profile](https://twitter.com/jonschlinkert)
|
240 | * [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
|
241 |
|
242 | ### License
|
243 |
|
244 | Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
|
245 | Released under the [MIT License](LICENSE).
|
246 |
|
247 | ***
|
248 |
|
249 | _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 22, 2019._ |
\ | No newline at end of file |