com.google.debugging.sourcemap

Class SourceMapGeneratorV3

java.lang.Object

com.google.debugging.sourcemap.SourceMapGeneratorV3

All Implemented Interfaces:

SourceMapGenerator

@GwtIncompatible(value="com.google.gson")
public final class SourceMapGeneratorV3
extends Object
implements SourceMapGenerator

Collects information mapping the generated (compiled) source back to its original source for debugging purposes. Source Map Revision 3 Proposal: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit?usp=sharing

Author:

[email protected] (John Lenz)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SourceMapGeneratorV3.ExtensionMergeAction This interface provides the merging strategy when an extension conflict appears because of merging two source maps on method mergeMapSection(int, int, java.lang.String).

Constructor Summary

Constructors

Constructor and Description
SourceMapGeneratorV3()

Method Summary

Modifier and Type	Method and Description
void	addExtension(String name, Object object) Adds field extensions to the json source map.
void	addMapping(String sourceName, String symbolName, FilePosition sourceStartPosition, FilePosition startPosition, FilePosition endPosition) Adds a mapping for the given node.
void	appendIndexMapTo(Appendable out, String name, List<SourceMapSection> sections) Appends the index source map to the given buffer.
void	appendTo(Appendable out, String name) Writes out the source map in the following format (line numbers are for reference only and are not part of the format): 1.
Object	getExtension(String name) Returns the value mapped by the specified extension or null if this extension does not exist.
boolean	hasExtension(String name) Check whether or not the sourcemap has an extension.
void	mergeMapSection(int line, int column, String mapSectionContents) Merges current mapping with mapSectionContents considering the offset (line, column).
void	mergeMapSection(int line, int column, String mapSectionContents, SourceMapGeneratorV3.ExtensionMergeAction mergeAction) Works like mergeMapSection(int, int, String), except that extensions from the @{code mapSectionContents} are merged to the top level source map.
void	removeExtension(String name) Removes an extension by name if present.
void	reset() Resets the source map for reuse.
void	setSourceRoot(String path) A prefix to be added to the beginning of each sourceName passed to addMapping(java.lang.String, java.lang.String, com.google.debugging.sourcemap.FilePosition, com.google.debugging.sourcemap.FilePosition, com.google.debugging.sourcemap.FilePosition).
void	setStartingPosition(int offsetLine, int offsetIndex) Sets the source code that exists in the buffer for which the generated code is being generated.
void	setWrapperPrefix(String prefix) Sets the prefix used for wrapping the generated source file before it is written.
void	validate(boolean validate) Whether to perform additional validation on the source map.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SourceMapGeneratorV3

public SourceMapGeneratorV3()

Method Detail

reset

public void reset()

Resets the source map for reuse. A reset needs to be called between each generated output file.

Specified by:

reset in interface SourceMapGenerator

validate

public void validate(boolean validate)

Description copied from interface: SourceMapGenerator

Whether to perform additional validation on the source map.

Specified by:

validate in interface SourceMapGenerator

Parameters:

validate - Whether to perform (potentially costly) validation on the generated source map.

setWrapperPrefix

public void setWrapperPrefix(String prefix)

Sets the prefix used for wrapping the generated source file before it is written. This ensures that the source map is adjusted for the change in character offsets.

Specified by:

setWrapperPrefix in interface SourceMapGenerator

Parameters:

prefix - The prefix that is added before the generated source code.

setStartingPosition

public void setStartingPosition(int offsetLine,
                                int offsetIndex)

Sets the source code that exists in the buffer for which the generated code is being generated. This ensures that the source map accurately reflects the fact that the source is being appended to an existing buffer and as such, does not start at line 0, position 0 but rather some other line and position.

Specified by:

setStartingPosition in interface SourceMapGenerator

Parameters:

offsetLine - The index of the current line being printed.

offsetIndex - The column index of the current character being printed.

addMapping

public void addMapping(String sourceName,
                       @Nullable
                       String symbolName,
                       FilePosition sourceStartPosition,
                       FilePosition startPosition,
                       FilePosition endPosition)

Adds a mapping for the given node. Mappings must be added in order.

Specified by:

addMapping in interface SourceMapGenerator

Parameters:

startPosition - The position on the starting line

endPosition - The position on the ending line.

sourceName - The file name to use in the generate source map to represent this source.

symbolName - The symbol name associated with this position in the source map.

sourceStartPosition - The starting position in the original source for represented range outputStartPosition to outputEndPosition in the generated file.

mergeMapSection

public void mergeMapSection(int line,
                            int column,
                            String mapSectionContents)
                     throws SourceMapParseException

Merges current mapping with mapSectionContents considering the offset (line, column). Any extension in the map section will be ignored.

Parameters:

line - The line offset

column - The column offset

mapSectionContents - The map section to be appended

Throws:

SourceMapParseException

mergeMapSection

public void mergeMapSection(int line,
                            int column,
                            String mapSectionContents,
                            SourceMapGeneratorV3.ExtensionMergeAction mergeAction)
                     throws SourceMapParseException

Works like mergeMapSection(int, int, String), except that extensions from the @{code mapSectionContents} are merged to the top level source map. For conflicts a mergeAction is performed.

Parameters:

line - The line offset

column - The column offset

mapSectionContents - The map section to be appended

mergeAction - The merge action for conflicting extensions

Throws:

SourceMapParseException

appendTo

public void appendTo(Appendable out,
                     String name)
              throws IOException

Writes out the source map in the following format (line numbers are for reference only and are not part of the format): 1. { 2. version: 3, 3. file: "out.js", 4. lineCount: 2, 5. sourceRoot: "", 6. sources: ["foo.js", "bar.js"], 7. names: ["src", "maps", "are", "fun"], 8. mappings: "a;;abcde,abcd,a;" 9. x_org_extension: value 10. } Line 1: The entire file is a single JSON object Line 2: File revision (always the first entry in the object) Line 3: The name of the file that this source map is associated with. Line 4: The number of lines represented in the source map. Line 5: An optional source root, useful for relocating source files on a server or removing repeated prefix values in the "sources" entry. Line 6: A list of sources used by the "mappings" entry relative to the sourceRoot. Line 7: A list of symbol names used by the "mapping" entry. This list may be incomplete. Line 8: The mappings field. Line 9: Any custom field (extension).

Specified by:

appendTo in interface SourceMapGenerator

Parameters:

out - The stream to which the map will be appended.

name - The name of the generated source file that this source map represents.

Throws:

IOException

setSourceRoot

public void setSourceRoot(String path)

A prefix to be added to the beginning of each sourceName passed to addMapping(java.lang.String, java.lang.String, com.google.debugging.sourcemap.FilePosition, com.google.debugging.sourcemap.FilePosition, com.google.debugging.sourcemap.FilePosition). Debuggers expect (prefix + sourceName) to be a URL for loading the source code.

Parameters:

path - The URL prefix to save in the sourcemap file. (Not validated.)

addExtension

public void addExtension(String name,
                         Object object)
                  throws SourceMapParseException

Adds field extensions to the json source map. The value is allowed to be any value accepted by json, eg. string, JsonObject, JsonArray, etc. Extensions must follow the format x_orgranization_field (based on V3 proposal), otherwise a SourceMapParseExtension will be thrown.

Parameters:

name - The name of the extension with format organization_field

object - The value of the extension as a valid json value

Throws:

SourceMapParseException - if extension name is malformed

removeExtension

public void removeExtension(String name)

Removes an extension by name if present.

Parameters:

name - The name of the extension with format organization_field

hasExtension

public boolean hasExtension(String name)

Check whether or not the sourcemap has an extension.

Parameters:

name - The name of the extension with format organization_field

Returns:

If the extension exist

getExtension

public Object getExtension(String name)

Returns the value mapped by the specified extension or null if this extension does not exist.

Parameters:

name -

Returns:

the extension value or null

appendIndexMapTo

public void appendIndexMapTo(Appendable out,
                             String name,
                             List<SourceMapSection> sections)
                      throws IOException

Appends the index source map to the given buffer.

Specified by:

appendIndexMapTo in interface SourceMapGenerator

Parameters:

out - The stream to which the map will be appended.

name - The name of the generated source file that this source map represents.

sections - An ordered list of map sections to include in the index.

Throws:

IOException