Package com.google.debugging.sourcemap

Class SourceMapGeneratorV3

  • All Implemented Interfaces:
    SourceMapGenerator
    public final class SourceMapGeneratorV3
extends java.lang.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

    • 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​(java.lang.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​(java.lang.String sourceName,
                       @Nullable
                       java.lang.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.

      • addSourcesContent

        public void addSourcesContent​(java.lang.String source,
                              java.lang.String content)
        Description copied from interface: SourceMapGenerator
        Adds a sourcesContent entry for the corresponding source.
        Specified by:
        addSourcesContent in interface SourceMapGenerator
        Parameters:
        source - The source name.
        content - The source content.

      • mergeMapSection

        public void mergeMapSection​(int line,
                            int column,
                            java.lang.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

      • appendTo

        public void appendTo​(java.lang.Appendable out,
                     @Nullable
                     java.lang.String name)
              throws java.io.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.    sourcesContent: ["var foo", "var bar"],
 8.    names: ["src", "maps", "are", "fun"],
 9.    mappings: "a;;abcde,abcd,a;"
 10.   x_org_extension: value
 11. }
        1. Line 1 : The entire file is a single JSON object
        2. Line 2 : File version (always the first entry in the object)
        3. Line 3 : [Optional] The name of the file that this source map is associated with.
        4. Line 4 : [Optional] The number of lines represented in the source map.
        5. Line 5 : [Optional] An optional source root, useful for relocating source files on a server or removing repeated prefix values in the "sources" entry.
        6. Line 6 : A list of sources used by the "mappings" entry relative to the sourceRoot.
        7. Line 7 : An optional list of the full content of the source files.
        8. Line 8 : A list of symbol names used by the "mapping" entry. This list may be incomplete. Line 9 : The mappings field.
        9. Line 10: 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:
        java.io.IOException

      • addExtension

        public void addExtension​(java.lang.String name,
                         java.lang.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​(java.lang.String name)
        Removes an extension by name if present.
        Parameters:
        name - The name of the extension with format organization_field

      • hasExtension

        public boolean hasExtension​(java.lang.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 java.lang.Object getExtension​(java.lang.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​(java.lang.Appendable out,
                             java.lang.String name,
                             java.util.List<SourceMapSection> sections)
                      throws java.io.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:
        java.io.IOException