source: trip-planner-front/node_modules/magic-string/README.md@ 8d391a1

Last change on this file since 8d391a1 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 9.1 KB
Line 
1# magic-string
2
3<a href="https://travis-ci.org/Rich-Harris/magic-string">
4 <img src="http://img.shields.io/travis/Rich-Harris/magic-string.svg"
5 alt="build status">
6</a>
7<a href="https://npmjs.org/package/magic-string">
8 <img src="https://img.shields.io/npm/v/magic-string.svg"
9 alt="npm version">
10</a>
11<a href="https://github.com/Rich-Harris/magic-string/blob/master/LICENSE.md">
12 <img src="https://img.shields.io/npm/l/magic-string.svg"
13 alt="license">
14</a>
15
16Suppose you have some source code. You want to make some light modifications to it - replacing a few characters here and there, wrapping it with a header and footer, etc - and ideally you'd like to generate a source map at the end of it. You've thought about using something like [recast](https://github.com/benjamn/recast) (which allows you to generate an AST from some JavaScript, manipulate it, and reprint it with a sourcemap without losing your comments and formatting), but it seems like overkill for your needs (or maybe the source code isn't JavaScript).
17
18Your requirements are, frankly, rather niche. But they're requirements that I also have, and for which I made magic-string. It's a small, fast utility for manipulating strings and generating sourcemaps.
19
20## Installation
21
22magic-string works in both node.js and browser environments. For node, install with npm:
23
24```bash
25npm i magic-string
26```
27
28To use in browser, grab the [magic-string.umd.js](https://unpkg.com/magic-string/dist/magic-string.umd.js) file and add it to your page:
29
30```html
31<script src='magic-string.umd.js'></script>
32```
33
34(It also works with various module systems, if you prefer that sort of thing - it has a dependency on [vlq](https://github.com/Rich-Harris/vlq).)
35
36## Usage
37
38These examples assume you're in node.js, or something similar:
39
40```js
41var MagicString = require( 'magic-string' );
42var s = new MagicString( 'problems = 99' );
43
44s.overwrite( 0, 8, 'answer' );
45s.toString(); // 'answer = 99'
46
47s.overwrite( 11, 13, '42' ); // character indices always refer to the original string
48s.toString(); // 'answer = 42'
49
50s.prepend( 'var ' ).append( ';' ); // most methods are chainable
51s.toString(); // 'var answer = 42;'
52
53var map = s.generateMap({
54 source: 'source.js',
55 file: 'converted.js.map',
56 includeContent: true
57}); // generates a v3 sourcemap
58
59require( 'fs' ).writeFile( 'converted.js', s.toString() );
60require( 'fs' ).writeFile( 'converted.js.map', map.toString() );
61```
62
63You can pass an options argument:
64
65```js
66var s = new MagicString( someCode, {
67 // both these options will be used if you later
68 // call `bundle.addSource( s )` - see below
69 filename: 'foo.js',
70 indentExclusionRanges: [/*...*/]
71});
72```
73
74## Methods
75
76### s.addSourcemapLocation( index )
77
78Adds the specified character index (with respect to the original string) to sourcemap mappings, if `hires` is `false` (see below).
79
80### s.append( content )
81
82Appends the specified content to the end of the string. Returns `this`.
83
84### s.appendLeft( index, content )
85
86Appends the specified `content` at the `index` in the original string. If a range *ending* with `index` is subsequently moved, the insert will be moved with it. Returns `this`. See also `s.prependLeft(...)`.
87
88### s.appendRight( index, content )
89
90Appends the specified `content` at the `index` in the original string. If a range *starting* with `index` is subsequently moved, the insert will be moved with it. Returns `this`. See also `s.prependRight(...)`.
91
92### s.clone()
93
94Does what you'd expect.
95
96### s.generateDecodedMap( options )
97
98Generates a sourcemap object with raw mappings in array form, rather than encoded as a string. See `generateMap` documentation below for options details. Useful if you need to manipulate the sourcemap further, but most of the time you will use `generateMap` instead.
99
100### s.generateMap( options )
101
102Generates a [version 3 sourcemap](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit). All options are, well, optional:
103
104* `file` - the filename where you plan to write the sourcemap
105* `source` - the filename of the file containing the original source
106* `includeContent` - whether to include the original content in the map's `sourcesContent` array
107* `hires` - whether the mapping should be high-resolution. Hi-res mappings map every single character, meaning (for example) your devtools will always be able to pinpoint the exact location of function calls and so on. With lo-res mappings, devtools may only be able to identify the correct line - but they're quicker to generate and less bulky. If sourcemap locations have been specified with `s.addSourceMapLocation()`, they will be used here.
108
109The returned sourcemap has two (non-enumerable) methods attached for convenience:
110
111* `toString` - returns the equivalent of `JSON.stringify(map)`
112* `toUrl` - returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
113
114```js
115code += '\n//# sourceMappingURL=' + map.toUrl();
116```
117
118### s.indent( prefix[, options] )
119
120Prefixes each line of the string with `prefix`. If `prefix` is not supplied, the indentation will be guessed from the original content, falling back to a single tab character. Returns `this`.
121
122The `options` argument can have an `exclude` property, which is an array of `[start, end]` character ranges. These ranges will be excluded from the indentation - useful for (e.g.) multiline strings.
123
124### s.insertLeft( index, content )
125
126**DEPRECATED** since 0.17 – use `s.appendLeft(...)` instead
127
128### s.insertRight( index, content )
129
130**DEPRECATED** since 0.17 – use `s.prependRight(...)` instead
131
132### s.locate( index )
133
134**DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
135
136### s.locateOrigin( index )
137
138**DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
139
140### s.move( start, end, newIndex )
141
142Moves the characters from `start` and `end` to `index`. Returns `this`.
143
144### s.overwrite( start, end, content[, options] )
145
146Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply. Returns `this`.
147
148The fourth argument is optional. It can have a `storeName` property — if `true`, the original name will be stored for later inclusion in a sourcemap's `names` array — and a `contentOnly` property which determines whether only the content is overwritten, or anything that was appended/prepended to the range as well.
149
150### s.prepend( content )
151
152Prepends the string with the specified content. Returns `this`.
153
154### s.prependLeft ( index, content )
155
156Same as `s.appendLeft(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
157
158### s.prependRight ( index, content )
159
160Same as `s.appendRight(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
161
162### s.remove( start, end )
163
164Removes the characters from `start` to `end` (of the original string, **not** the generated string). Removing the same content twice, or making removals that partially overlap, will cause an error. Returns `this`.
165
166### s.slice( start, end )
167
168Returns the content of the generated string that corresponds to the slice between `start` and `end` of the original string. Throws error if the indices are for characters that were already removed.
169
170### s.snip( start, end )
171
172Returns a clone of `s`, with all content before the `start` and `end` characters of the original string removed.
173
174### s.toString()
175
176Returns the generated string.
177
178### s.trim([ charType ])
179
180Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start and end. Returns `this`.
181
182### s.trimStart([ charType ])
183
184Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start. Returns `this`.
185
186### s.trimEnd([ charType ])
187
188Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the end. Returns `this`.
189
190### s.trimLines()
191
192Removes empty lines from the start and end. Returns `this`.
193
194### s.isEmpty()
195
196Returns true if the resulting source is empty (disregarding white space).
197
198## Bundling
199
200To concatenate several sources, use `MagicString.Bundle`:
201
202```js
203var bundle = new MagicString.Bundle();
204
205bundle.addSource({
206 filename: 'foo.js',
207 content: new MagicString( 'var answer = 42;' )
208});
209
210bundle.addSource({
211 filename: 'bar.js',
212 content: new MagicString( 'console.log( answer )' )
213});
214
215// Advanced: a source can include an `indentExclusionRanges` property
216// alongside `filename` and `content`. This will be passed to `s.indent()`
217// - see documentation above
218
219bundle.indent() // optionally, pass an indent string, otherwise it will be guessed
220 .prepend( '(function () {\n' )
221 .append( '}());' );
222
223bundle.toString();
224// (function () {
225// var answer = 42;
226// console.log( answer );
227// }());
228
229// options are as per `s.generateMap()` above
230var map = bundle.generateMap({
231 file: 'bundle.js',
232 includeContent: true,
233 hires: true
234});
235```
236
237As an alternative syntax, if you a) don't have `filename` or `indentExclusionRanges` options, or b) passed those in when you used `new MagicString(...)`, you can simply pass the `MagicString` instance itself:
238
239```js
240var bundle = new MagicString.Bundle();
241var source = new MagicString( someCode, {
242 filename: 'foo.js'
243});
244
245bundle.addSource( source );
246```
247
248## License
249
250MIT
Note: See TracBrowser for help on using the repository browser.