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

      • 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​(@Nullable 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()

      • reconcileOptionsWithGuards

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

      • initWithTypedAstFilesystem

        @GwtIncompatible
public final void initWithTypedAstFilesystem​(java.util.List<SourceFile> externs,
                                             java.util.List<SourceFile> sources,
                                             CompilerOptions options,
                                             java.io.InputStream typedAstListStream)
        Initializes a compiler that will use pre-compiled TypedAst files instead of reading the source from disk

      • initModulesWithTypedAstFilesystem

        @GwtIncompatible
public void initModulesWithTypedAstFilesystem​(java.util.List<SourceFile> externs,
                                              java.util.List<JSChunk> modules,
                                              CompilerOptions options,
                                              java.io.InputStream typedAstListStream)
        Initializes a compiler that will use pre-compiled TypedAst files instead of reading the source from disk

      • initRuntimeLibraryTypedAsts

        @GwtIncompatible
public void initRuntimeLibraryTypedAsts​(com.google.common.base.Optional<ColorPool.Builder> colorPoolBuilder)
        Description copied from class: AbstractCompiler
        Deserialize runtime libraries from a TypedAST packaged as a JAR resource and reconcile their Colors with the current inputs.

        This method must be called anywhere that Colors are reconciled for application to the AST. Otherwise Color information won't be consistent. `colorPoolBuilder` must be the same builder as used for the other inputs, and the caller retains ownership.

        Overrides:
        initRuntimeLibraryTypedAsts in class AbstractCompiler
        Parameters:
        colorPoolBuilder - if present, includes inferred optimization colors on the deserialized ASTs. If absent, does not include colors.

      • init

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

      • initModules

        public void initModules​(java.util.List<SourceFile> externs,
                        java.util.List<JSChunk> 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 Result compile​(java.util.List<SourceFile> externs,
                      java.util.List<SourceFile> 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 Result compileModules​(java.util.List<SourceFile> externs,
                             java.util.List<JSChunk> 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).

      • getModules

        public @Nullable java.lang.Iterable<JSChunk> 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.

      • isTypeRegistryCleared

        public boolean isTypeRegistryCleared()
        Description copied from class: AbstractCompiler
        Returns `true` when type checking has run, but the type registry has been cleared.

        See also `clearJSTypeRegistry()`.

        Specified by:
        isTypeRegistryCleared in class AbstractCompiler

      • forwardDeclareType

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

      • getTypedScopeCreator

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

      • buildKnownSymbolTable

        public SymbolTable buildKnownSymbolTable()

      • maybeSetTracker

        public void maybeSetTracker()

      • newCompilerOptions

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

      • parseSyntheticCode

        public Node parseSyntheticCode​(java.lang.String fileName,
                               java.lang.String js)
        Description copied from class: AbstractCompiler
        Parses code for injecting, and associate it with a given source file.
        Specified by:
        parseSyntheticCode in class AbstractCompiler

      • 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​(JSChunk module)
        Converts the parse tree for a module back to JS code.

        Consider using toSource(JSChunk, LicenseTracker) for better license handling. This call will emit all license text attached to all direct inputs to the module, which can be very inefficient.

      • toSource

        public java.lang.String toSource​(CodePrinter.LicenseTracker licenseTracker,
                                 JSChunk module)
        Converts the parse tree for a module back to JS code, using the given License Tracker to determine which licenses should be emitted before the source code.
        Parameters:
        licenseTracker - The license tracker implementation to use. Compiler.ChunkGraphAwareLicenseTracker is a suitable implementation when this method is being called on each module in the chunk graph in dependency order.

      • toSource

        @Deprecated
public void toSource​(Compiler.CodeBuilder cb,
                     int inputSeqNum,
                     Node root)
        Deprecated.
        use toSource(CodeBuilder, LicenseTracker, int, Node) instead for better license tracking.
        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 void toSource​(Compiler.CodeBuilder cb,
                     CodePrinter.LicenseTracker licenseTracker,
                     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.

        The LicenseTracker provided determines which licenses attached to the nodes visited should be included in the output. When building a single JS bundle, consider using the Compiler.SingleBinaryLicenseTracker implementation.

      • 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

      • getLicenseForFile

        public static @Nullable java.lang.String getLicenseForFile​(AbstractCompiler compiler,
                                                           @Nullable java.lang.String fileName)

      • toSourceArray

        public java.lang.String[] toSourceArray​(CodePrinter.LicenseTracker licenseTracker,
                                        JSChunk module)
        Converts the parse tree for each input in a module back to JS code, using the given License Tracker implementation to decide which licenses should be emitted before each input file.
        Parameters:
        licenseTracker - The license tracker implementation to use. Compiler.ChunkGraphAwareLicenseTracker is a suitable implementation when this method is being called on each module in the chunk graph in dependency order - see its javadoc on how to use it correctly.
        module - the chunk being converted to source.

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

      • getSourceMapping

        public @Nullable 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 @Nullable 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 @Nullable 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 @Nullable 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 JSChunk module)

      • getSourceMap

        public SourceMap getSourceMap()

      • setCssNames

        public void setCssNames​(java.util.LinkedHashMap<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

      • getInstrumentationMapping

        public VariableMap getInstrumentationMapping()

      • 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.

      • getExternProperties

        public com.google.common.collect.ImmutableSet<java.lang.String> getExternProperties()
        Description copied from class: AbstractCompiler
        Gets the names of the properties defined in externs or null if GatherExternProperties pass was not run yet.
        Specified by:
        getExternProperties in class AbstractCompiler

      • setAccessorSummary

        public void setAccessorSummary​(com.google.javascript.jscomp.AccessorSummary summary)
        Description copied from class: AbstractCompiler
        Sets the summary of properties with getters and setters.
        Specified by:
        setAccessorSummary in class AbstractCompiler

      • ensureLibraryInjected

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

      • 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()

      • restoreFromState

        protected void restoreFromState​(Compiler.CompilerState compilerState)
        Restore the portions of the compiler state that don't require access to the serialized AST.

      • saveState

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

      • restoreState

        @GwtIncompatible("ClassNotFoundException")
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()