diff options
Diffstat (limited to 'node_modules/source-map/README.md')
| -rw-r--r-- | node_modules/source-map/README.md | 185 |
1 files changed, 139 insertions, 46 deletions
diff --git a/node_modules/source-map/README.md b/node_modules/source-map/README.md index 32813394..56e5ac3e 100644 --- a/node_modules/source-map/README.md +++ b/node_modules/source-map/README.md @@ -2,6 +2,8 @@ [](https://travis-ci.org/mozilla/source-map) +[](https://coveralls.io/github/mozilla/source-map) + [](https://www.npmjs.com/package/source-map) This is a library to generate and consume the source map format @@ -15,7 +17,12 @@ This is a library to generate and consume the source map format ## Use on the Web - <script src="https://raw.githubusercontent.com/mozilla/source-map/master/dist/source-map.min.js" defer></script> + <script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script> + <script> + sourceMap.SourceMapConsumer.initialize({ + "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm" + }); + </script> -------------------------------------------------------------------------------- @@ -32,7 +39,10 @@ This is a library to generate and consume the source map format - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api) - [API](#api) - [SourceMapConsumer](#sourcemapconsumer) + - [SourceMapConsumer.initialize(options)](#sourcemapconsumerinitializeoptions) - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap) + - [SourceMapConsumer.with](#sourcemapconsumerwith) + - [SourceMapConsumer.prototype.destroy()](#sourcemapconsumerprototypedestroy) - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans) - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition) - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition) @@ -67,7 +77,7 @@ This is a library to generate and consume the source map format ### Consuming a source map ```js -var rawSourceMap = { +const rawSourceMap = { version: 3, file: 'min.js', names: ['bar', 'baz', 'n'], @@ -76,30 +86,33 @@ var rawSourceMap = { mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA' }; -var smc = new SourceMapConsumer(rawSourceMap); - -console.log(smc.sources); -// [ 'http://example.com/www/js/one.js', -// 'http://example.com/www/js/two.js' ] - -console.log(smc.originalPositionFor({ - line: 2, - column: 28 -})); -// { source: 'http://example.com/www/js/two.js', -// line: 2, -// column: 10, -// name: 'n' } - -console.log(smc.generatedPositionFor({ - source: 'http://example.com/www/js/two.js', - line: 2, - column: 10 -})); -// { line: 2, column: 28 } - -smc.eachMapping(function (m) { - // ... +const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => { + + console.log(consumer.sources); + // [ 'http://example.com/www/js/one.js', + // 'http://example.com/www/js/two.js' ] + + console.log(consumer.originalPositionFor({ + line: 2, + column: 28 + })); + // { source: 'http://example.com/www/js/two.js', + // line: 2, + // column: 10, + // name: 'n' } + + console.log(consumer.generatedPositionFor({ + source: 'http://example.com/www/js/two.js', + line: 2, + column: 10 + })); + // { line: 2, column: 28 } + + consumer.eachMapping(function (m) { + // ... + }); + + return computeWhatever(); }); ``` @@ -182,10 +195,27 @@ const sourceMap = require("devtools/toolkit/sourcemap/source-map.js"); ### SourceMapConsumer -A SourceMapConsumer instance represents a parsed source map which we can query +A `SourceMapConsumer` instance represents a parsed source map which we can query for information about the original file positions by giving it a file position in the generated source. +#### SourceMapConsumer.initialize(options) + +When using `SourceMapConsumer` outside of node.js, for example on the Web, it +needs to know from what URL to load `lib/mappings.wasm`. You must inform it by +calling `initialize` before constructing any `SourceMapConsumer`s. + +The options object has the following properties: + +* `"lib/mappings.wasm"`: A `String` containing the URL of the + `lib/mappings.wasm` file, or an `ArrayBuffer` with the contents of `lib/mappings.wasm`. + +```js +sourceMap.SourceMapConsumer.initialize({ + "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm" +}); +``` + #### new SourceMapConsumer(rawSourceMap) The only parameter is the raw source map (either as a string which can be @@ -207,10 +237,62 @@ following attributes: * `file`: Optional. The generated filename this source map is associated with. +The promise of the constructed souce map consumer is returned. + +When the `SourceMapConsumer` will no longer be used anymore, you must call its +`destroy` method. + +```js +const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData); +doStuffWith(consumer); +consumer.destroy(); +``` + +Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember +to call `destroy`. + +#### SourceMapConsumer.with + +Construct a new `SourceMapConsumer` from `rawSourceMap` and `sourceMapUrl` +(see the `SourceMapConsumer` constructor for details. Then, invoke the `async +function f(SourceMapConsumer) -> T` with the newly constructed consumer, wait +for `f` to complete, call `destroy` on the consumer, and return `f`'s return +value. + +You must not use the consumer after `f` completes! + +By using `with`, you do not have to remember to manually call `destroy` on +the consumer, since it will be called automatically once `f` completes. + ```js -var consumer = new sourceMap.SourceMapConsumer(rawSourceMapJsonData); +const xSquared = await SourceMapConsumer.with( + myRawSourceMap, + null, + async function (consumer) { + // Use `consumer` inside here and don't worry about remembering + // to call `destroy`. + + const x = await whatever(consumer); + return x * x; + } +); + +// You may not use that `consumer` anymore out here; it has +// been destroyed. But you can use `xSquared`. +console.log(xSquared); ``` +#### SourceMapConsumer.prototype.destroy() + +Free this source map consumer's associated wasm data that is manually-managed. + +```js +consumer.destroy(); +``` + +Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember +to call `destroy`. + #### SourceMapConsumer.prototype.computeColumnSpans() Compute the last column for each generated mapping. The last column is @@ -239,7 +321,6 @@ consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" }) // { line: 2, // column: 20, // lastColumn: Infinity } ] - ``` #### SourceMapConsumer.prototype.originalPositionFor(generatedPosition) @@ -248,9 +329,13 @@ Returns the original source, line, and column information for the generated source's line and column positions provided. The only argument is an object with the following properties: -* `line`: The line number in the generated source. +* `line`: The line number in the generated source. Line numbers in + this library are 1-based (note that the underlying source map + specification uses 0-based line numbers -- this library handles the + translation). -* `column`: The column number in the generated source. +* `column`: The column number in the generated source. Column numbers + in this library are 0-based. * `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest @@ -264,10 +349,10 @@ and an object is returned with the following properties: available. * `line`: The line number in the original source, or null if this information is - not available. + not available. The line number is 1-based. * `column`: The column number in the original source, or null if this - information is not available. + information is not available. The column number is 0-based. * `name`: The original identifier, or null if this information is not available. @@ -293,15 +378,19 @@ the following properties: * `source`: The filename of the original source. -* `line`: The line number in the original source. +* `line`: The line number in the original source. The line number is + 1-based. -* `column`: The column number in the original source. +* `column`: The column number in the original source. The column + number is 0-based. and an object is returned with the following properties: -* `line`: The line number in the generated source, or null. +* `line`: The line number in the generated source, or null. The line + number is 1-based. -* `column`: The column number in the generated source, or null. +* `column`: The column number in the generated source, or null. The + column number is 0-based. ```js consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 }) @@ -322,15 +411,19 @@ The only argument is an object with the following properties: * `source`: The filename of the original source. -* `line`: The line number in the original source. +* `line`: The line number in the original source. The line number is + 1-based. -* `column`: Optional. The column number in the original source. +* `column`: Optional. The column number in the original source. The + column number is 0-based. and an array of objects is returned, each with the following properties: -* `line`: The line number in the generated source, or null. +* `line`: The line number in the generated source, or null. The line + number is 1-based. -* `column`: The column number in the generated source, or null. +* `column`: The column number in the generated source, or null. The + column number is 0-based. ```js consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" }) @@ -534,10 +627,11 @@ use before outputting the generated JS and source map. #### new SourceNode([line, column, source[, chunk[, name]]]) * `line`: The original line number associated with this source node, or null if - it isn't associated with an original line. + it isn't associated with an original line. The line number is 1-based. * `column`: The original column number associated with this source node, or null - if it isn't associated with an original column. + if it isn't associated with an original column. The column number + is 0-based. * `source`: The original source's filename; null if no filename is provided. @@ -566,9 +660,8 @@ Creates a SourceNode from generated code and a SourceMapConsumer. should be relative to. ```js -var consumer = new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8")); -var node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), - consumer); +const consumer = await new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8")); +const node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), consumer); ``` #### SourceNode.prototype.add(chunk) |