Package com.google.javascript.jscomp

Class Compiler

  • All Implemented Interfaces:
    CompilerInputProvider, ErrorHandler, SourceExcerptProvider, SourceFileMapping
    public class Compiler
extends AbstractCompiler
implements ErrorHandler, SourceFileMapping
    Compiler (and the other classes in this package) does the following:
    • parses JS code
    • checks for undefined variables
    • performs optimizations such as constant folding and constants inlining
    • renames variables (to short names)
    • outputs compact JavaScript code
    External variables are declared in 'externs' files. For instance, the file may include definitions for global javascript/browser objects such as window, document.

    • Field Detail

      • OPTIMIZE_LOOP_ERROR

        public static final DiagnosticType OPTIMIZE_LOOP_ERROR
        Error strings used for reporting JSErrors

      • MOTION_ITERATIONS_ERROR

        public static final DiagnosticType MOTION_ITERATIONS_ERROR

      • logger

        public static final java.util.logging.Logger logger
        Logger for the whole com.google.javascript.jscomp domain - setting configuration for this logger affects all loggers in other classes within the compiler.

      • recentChange

        protected final com.google.javascript.jscomp.RecentChange recentChange

    • Constructor Detail

      • Compiler

        public Compiler()
        Creates a Compiler that reports errors and warnings to its logger.

      • Compiler

        public Compiler​(java.io.PrintStream outStream)
        Creates a Compiler that reports errors and warnings to an output stream.

      • Compiler

        public Compiler​(ErrorManager errorManager)
        Creates a Compiler that uses a custom error manager.

    • Method Detail

      • setErrorManager

        public void setErrorManager​(ErrorManager errorManager)
        Sets the error manager.
        Parameters:
        errorManager - the error manager, it cannot be null

      • initOptions

        public void initOptions​(CompilerOptions options)
        Initializes the compiler options. It's called as part of a normal compile() job. Public for the callers that are not doing a normal compile() job.

      • printConfig

        public void printConfig​(java.io.PrintStream printStream)

      • reconcileOptionsWithGuards

        protected void reconcileOptionsWithGuards()
        When the CompilerOptions and its WarningsGuard overlap, reconcile any discrepancies.

      • init

        public final <T1 extends SourceFile,​T2 extends SourceFile> void init​(java.util.List<T1> externs,
                                                                           java.util.List<T2> sources,
                                                                           CompilerOptions options)
        Initializes the instance state needed for a compile job.

      • initModules

        public <T extends SourceFile> void initModules​(java.util.List<T> externs,
                                               java.util.List<JSModule> modules,
                                               CompilerOptions options)
        Initializes the instance state needed for a compile job if the sources are in modules.

      • initBasedOnOptions

        public void initBasedOnOptions()
        Do any initialization that is dependent on the compiler options.

      • joinPathParts

        public static java.lang.String joinPathParts​(java.lang.String... pathParts)
        Creates an OS specific path string from parts

      • compile

        public <T1 extends SourceFile,​T2 extends SourceFile> Result compile​(java.util.List<T1> externs,
                                                                          java.util.List<T2> inputs,
                                                                          CompilerOptions options)
        Compiles a list of inputs.

        This is a convenience method to wrap up all the work of compilation, including generating the error and warning report.

        NOTE: All methods called here must be public, because client code must be able to replicate and customize this.

      • generateReport

        public void generateReport()
        Generates a report of all warnings and errors found during compilation to stderr.

        Client code must call this method explicitly if it doesn't use one of the convenience methods that do so automatically.

        Always call this method, even if the compiler throws an exception. The report will include information about the exception.

      • compileModules

        public <T extends SourceFile> Result compileModules​(java.util.List<T> externs,
                                                    java.util.List<JSModule> modules,
                                                    CompilerOptions options)
        Compiles a list of modules.

        This is a convenience method to wrap up all the work of compilation, including generating the error and warning report.

        NOTE: All methods called here must be public, because client code must be able to replicate and customize this.

      • disableThreads

        public void disableThreads()
        Disable threads. This is for clients that run on AppEngine and don't have threads.

      • setTimeout

        public void setTimeout​(int timeout)
        Sets the timeout when Compiler is run in a thread
        Parameters:
        timeout - seconds to wait before timeout

      • performPostCompilationTasks

        public void performPostCompilationTasks()
        Performs all the bookkeeping required at the end of a compilation.

        This method must be called if the compilation makes it as far as doing checks.

        DON'T call it if the compiler threw an exception.

        DO call it even when hasErrors() returns true.

      • parseForCompilation

        public void parseForCompilation()
        Parses input files in preparation for compilation.

        Either init() or initModules() must be called first to set up the input files to be read.

        TODO(bradfordcsmith): Rename this to parse()

      • parse

        public void parse()
        Parses input files without doing progress tracking that is part of a full compile.

        Either init() or initModules() must be called first to set up the input files to be read.

        TODO(bradfordcsmith): Rename this to parseIndependentOfCompilation() or similar.

      • createPassConfigInternal

        protected PassConfig createPassConfigInternal()
        Create the passes object. Clients should use setPassConfig instead of overriding this.

      • setPassConfig

        public void setPassConfig​(PassConfig passes)
        Parameters:
        passes - The PassConfig to use with this Compiler.
        Throws:
        java.lang.NullPointerException - if passes is null
        java.lang.IllegalStateException - if this.passes has already been assigned

      • whitespaceOnlyPasses

        public void whitespaceOnlyPasses()

      • transpileAndDontCheck

        public void transpileAndDontCheck()

      • getResult

        public Result getResult()
        Returns the result of the compilation.

      • getErrors

        public com.google.common.collect.ImmutableList<JSError> getErrors()
        Returns the list of errors (never null).

      • getWarnings

        public com.google.common.collect.ImmutableList<JSError> getWarnings()
        Returns the list of warnings (never null).

      • removeExternInput

        protected void removeExternInput​(InputId id)
        Removes an input file from AST.
        Parameters:
        id - The id of the input to be removed.

      • getModules

        @Nullable
public java.lang.Iterable<JSModule> getModules()
        Gets the JS source modules in dependency order.

        Returns null if #init or #initModules hasn't been called yet. Otherwise, the result is always non-empty, even in the degenerate case where there's only one module.

      • forwardDeclareType

        public void forwardDeclareType​(java.lang.String typeName)

      • getTypedScopeCreator

        public com.google.javascript.jscomp.TypedScopeCreator getTypedScopeCreator()

      • buildKnownSymbolTable

        public SymbolTable buildKnownSymbolTable()

      • maybeSetTracker

        public void maybeSetTracker()

      • newCompilerOptions

        protected CompilerOptions newCompilerOptions()
        Allow subclasses to override the default CompileOptions object.

      • parseSyntheticCode

        protected Node parseSyntheticCode​(java.lang.String js)

      • toSource

        public java.lang.String toSource()
        Converts the main parse tree back to JS code.
        Specified by:
        toSource in class AbstractCompiler

      • toSource

        public java.lang.String toSource​(JSModule module)
        Converts the parse tree for a module back to JS code.

      • toSource

        public void toSource​(Compiler.CodeBuilder cb,
                     int inputSeqNum,
                     Node root)
        Writes out JS code from a root node. If printing input delimiters, this method will attach a comment to the start of the text indicating which input the output derived from. If there were any preserve annotations within the root's source, they will also be printed in a block comment at the beginning of the output.

      • toSource

        public java.lang.String toSource​(Node n)
        Generates JavaScript source code for an AST, doesn't generate source map info.
        Specified by:
        toSource in class AbstractCompiler

      • toSourceArray

        public java.lang.String[] toSourceArray()
        Converts the parse tree for each input back to JS code.

      • toSourceArray

        public java.lang.String[] toSourceArray​(JSModule module)
        Converts the parse tree for each input in a module back to JS code.

      • getExternsRoot

        protected Node getExternsRoot()

      • getJsRoot

        protected Node getJsRoot()

      • getChangeStamp

        public int getChangeStamp()

      • incrementChangeStamp

        public void incrementChangeStamp()

      • reportChangeToChangeScope

        public void reportChangeToChangeScope​(Node changeScopeRoot)
        Description copied from class: AbstractCompiler
        Mark modifications in a scope that is different than the Compiler.currentScope use this (eg, InlineVariables and many others)
        Specified by:
        reportChangeToChangeScope in class AbstractCompiler

      • reportFunctionDeleted

        public void reportFunctionDeleted​(Node n)

      • reportChangeToEnclosingScope

        public void reportChangeToEnclosingScope​(Node n)
        Description copied from class: AbstractCompiler
        Passes that make modifications in a scope that is different than the Compiler.currentScope use this (eg, InlineVariables and many others)
        Specified by:
        reportChangeToEnclosingScope in class AbstractCompiler

      • getDiagnosticGroups

        public DiagnosticGroups getDiagnosticGroups()
        The warning classes that are available from the command-line, and are suppressible by the @suppress annotation.

      • report

        public void report​(CheckLevel ignoredLevel,
                   JSError error)
        Specified by:
        report in interface ErrorHandler
        Parameters:
        ignoredLevel - the reporting level
        error - the error to report

      • getErrorCount

        public int getErrorCount()
        Gets the number of errors.

      • getWarningCount

        public int getWarningCount()
        Gets the number of warnings.

      • hasErrors

        public boolean hasErrors()
        Consults the ErrorManager to see if we've encountered errors that should halt compilation.

        If CompilerOptions.canContinueAfterErrors() is true, this function always returns false without consulting the error manager. The error manager will continue to be told about new errors and warnings, but the compiler will complete compilation of all inputs.

      • getSourceFileContentByName

        public java.lang.CharSequence getSourceFileContentByName​(java.lang.String sourceName)

      • getSourceMapping

        @Nullable
public com.google.debugging.sourcemap.proto.Mapping.OriginalMapping getSourceMapping​(java.lang.String sourceName,
                                                                                     int lineNumber,
                                                                                     int columnNumber)
        Description copied from interface: SourceFileMapping
        Returns the original mapping for the file name, line number and column position found in the source map. Returns null if none is found.
        Specified by:
        getSourceMapping in interface SourceExcerptProvider
        Specified by:
        getSourceMapping in interface SourceFileMapping
        lineNumber - The line number, 1-based.
        columnNumber - The column index, 1-based.

      • getSourceLine

        public java.lang.String getSourceLine​(java.lang.String sourceName,
                                      int lineNumber)
        Description copied from interface: SourceExcerptProvider
        Get the line indicated by the line number. This call will return only the specific line.
        Specified by:
        getSourceLine in interface SourceExcerptProvider
        lineNumber - the line number, 1 being the first line of the file
        Returns:
        the line indicated, or null if it does not exist

      • getSourceLines

        public Region getSourceLines​(java.lang.String sourceName,
                             int lineNumber,
                             int length)
        Description copied from interface: SourceExcerptProvider
        Gets the specific lines returned by the beginning and excerpt length. Must not start or end with a carriage return. Implementations may decide to truncate lines but will always include the first line and never be longer than the specified length.
        Specified by:
        getSourceLines in interface SourceExcerptProvider
        lineNumber - the line number, 1 being the first line of the file
        length - the desired length of the excerpt (in chars). If -1, returns just a single line. Otherwise, returns as many lines as needed. (including the remainder of the last line)
        Returns:
        the region around the line number indicated, or null if it does not exist

      • getSourceRegion

        public Region getSourceRegion​(java.lang.String sourceName,
                              int lineNumber)
        Description copied from interface: SourceExcerptProvider
        Get a region around the indicated line number. The exact definition of a region is implementation specific, but it must contain the line indicated by the line number. A region must not start or end by a carriage return.
        Specified by:
        getSourceRegion in interface SourceExcerptProvider
        lineNumber - the line number, 1 being the first line of the file
        Returns:
        the region around the line number indicated, or null if it does not exist

      • getNodeForCodeInsertion

        protected Node getNodeForCodeInsertion​(@Nullable
                                       JSModule module)

      • getSourceMap

        public SourceMap getSourceMap()

      • setCssNames

        public void setCssNames​(java.util.Map<java.lang.String,​java.lang.Integer> cssNames)
        Description copied from class: AbstractCompiler
        Sets the css names found during compilation.
        Specified by:
        setCssNames in class AbstractCompiler

      • setIdGeneratorMap

        public void setIdGeneratorMap​(java.lang.String serializedIdMappings)
        Description copied from class: AbstractCompiler
        Sets the id generator for cross-module motion.
        Specified by:
        setIdGeneratorMap in class AbstractCompiler

      • addExportedNames

        public void addExportedNames​(java.util.Set<java.lang.String> exportedNames)
        Description copied from class: AbstractCompiler
        Adds exported names to keep track.
        Specified by:
        addExportedNames in class AbstractCompiler

      • setLoggingLevel

        public static void setLoggingLevel​(java.util.logging.Level level)
        Sets the logging level for the com.google.javascript.jscomp package.

      • getAstDotGraph

        public java.lang.String getAstDotGraph()
                                throws java.io.IOException
        Gets the DOT graph of the AST generated at the end of compilation.
        Throws:
        java.io.IOException

      • getInputsById

        public java.util.Map<InputId,​CompilerInput> getInputsById()
        Returns an unmodifiable view of the compiler inputs indexed by id.

      • getProgress

        public double getProgress()
        Specified by:
        getProgress in class AbstractCompiler
        Returns:
        a number in [0,1] range indicating an approximate progress of the last compile. Note this should only be used as a hint and no assumptions should be made on accuracy, even a completed compile may choose not to set this to 1.0 at the end.

      • replaceScript

        public void replaceScript​(JsAst ast)
        Replaces one file in a hot-swap mode. The given JsAst should be made from a new version of a file that already was present in the last compile call. If the file is new, this will silently ignored.
        Parameters:
        ast - the ast of the file that is being replaced

      • addNewScript

        public void addNewScript​(JsAst ast)
        Adds a new Script AST to the compile state. If a script for the same file already exists the script will not be added, instead a call to #replaceScript should be used.
        Parameters:
        ast - the ast of the new file

      • ensureLibraryInjected

        protected Node ensureLibraryInjected​(java.lang.String resourceName,
                                     boolean force)

      • getReleaseVersion

        @GwtIncompatible("java.util.ResourceBundle")
public static java.lang.String getReleaseVersion()
        Returns the compiler version baked into the jar.

      • getReleaseDate

        @GwtIncompatible("java.util.ResourceBundle")
public static java.lang.String getReleaseDate()
        Returns the compiler date baked into the jar.

      • getComments

        public java.util.List<Comment> getComments​(java.lang.String filename)

      • initWebpackMap

        public void initWebpackMap​(com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.String> inputPathByWebpackId)

      • createCompilerExecutor

        protected com.google.javascript.jscomp.CompilerExecutor createCompilerExecutor()

      • getCompilerExecutor

        protected com.google.javascript.jscomp.CompilerExecutor getCompilerExecutor()

      • saveState

        @GwtIncompatible("ObjectOutputStream")
public void saveState​(java.io.OutputStream outputStream)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • restoreState

        @GwtIncompatible("ObjectInputStream")
public void restoreState​(java.io.InputStream inputStream)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • resetAndIntitializeSourceMap

        public void resetAndIntitializeSourceMap()