Modules (181)

JSUtils

Description

Set of utilities for simple parsing of JS text.

Dependencies

Variables

Private

_changedDocumentTracker

Tracks dirty documents between invocations of findMatchingFunctions.

Type
ChangedDocumentTracker
    var _changedDocumentTracker = new ChangedDocumentTracker();

Functions

Private

_computeOffsets

doc non-nullable Document
functionName non-nullable string
functions non-nullable Array.<{offsetStart: number, offsetEnd: number}>
rangeResults non-nullable Array.<{document: Document, name: string, lineStart: number, lineEnd: number}>
    function _computeOffsets(doc, functionName, functions, rangeResults) {
        var text    = doc.getText(),
            lines   = StringUtils.getLines(text);

        functions.forEach(function (funcEntry) {
            if (!funcEntry.offsetEnd) {
                PerfUtils.markStart(PerfUtils.JSUTILS_END_OFFSET);

                funcEntry.offsetEnd = _getFunctionEndOffset(text, funcEntry.offsetStart);
                funcEntry.lineStart = StringUtils.offsetToLineNum(lines, funcEntry.offsetStart);
                funcEntry.lineEnd   = StringUtils.offsetToLineNum(lines, funcEntry.offsetEnd);

                PerfUtils.addMeasurement(PerfUtils.JSUTILS_END_OFFSET);
            }

            rangeResults.push({
                document:   doc,
                name:       functionName,
                lineStart:  funcEntry.lineStart,
                lineEnd:    funcEntry.lineEnd
            });
        });
    }
Private

_findAllFunctionsInText

text non-nullable string
Document text
Returns: Object.<string,Array.<{offsetStart: number,offsetEnd: number}>
    function _findAllFunctionsInText(text) {
        var AST,
            results = {},
            functionName,
            resultNode,
            memberPrefix,
            match;
   
        PerfUtils.markStart(PerfUtils.JSUTILS_REGEXP);
        
        try {
            AST = Acorn.parse(text, {locations: true});
        } catch (e) {
            AST = AcornLoose.parse_dammit(text, {locations: true});
        }
        
        function _addResult(node, offset, prefix) {
            memberPrefix = prefix ? prefix + " - " : "";
            resultNode = node.id || node.key || node;
            functionName = resultNode.name;
            if (!Array.isArray(results[functionName])) {
                results[functionName] = [];
            }

            results[functionName].push(
                {
                    offsetStart: offset || node.start,
                    label: memberPrefix ? memberPrefix + functionName : null,
                    location: resultNode.loc
                }
            );
        }
        
        ASTWalker.simple(AST, {
Private

_getFunctionsForFile

Resolves with a record containing the Document or FileInfo and an Array of all function names with offsets for the specified file. Results may be cached.

fileInfo FileInfo
Returns: $.Promise
A promise resolved with a document info object that contains a map of all function names from the document and each function's start offset.
    function _getFunctionsForFile(fileInfo) {
        var result = new $.Deferred();

        _shouldGetFromCache(fileInfo)
            .done(function (useCache) {
                if (useCache) {
                    // Return cached data. doc property is undefined since we hit the cache.
                    // _getOffsets() will fetch the Document if necessary.
                    result.resolve({
Private

_getFunctionsInFiles

fileInfos Array.<FileInfo>
Returns: $.Promise
A promise resolved with an array of document info objects that each contain a map of all function names from the document and each function's start offset.
    function _getFunctionsInFiles(fileInfos) {
        var result      = new $.Deferred(),
            docEntries  = [];

        PerfUtils.markStart(PerfUtils.JSUTILS_GET_ALL_FUNCTIONS);

        Async.doInParallel(fileInfos, function (fileInfo) {
            var oneResult = new $.Deferred();

            _getFunctionsForFile(fileInfo)
                .done(function (docInfo) {
                    docEntries.push(docInfo);
                })
                .always(function (error) {
                    // If one file fails, continue to search
                    oneResult.resolve();
                });

            return oneResult.promise();
        }).always(function () {
            // Reset ChangedDocumentTracker now that the cache is up to date.
            _changedDocumentTracker.reset();

            PerfUtils.addMeasurement(PerfUtils.JSUTILS_GET_ALL_FUNCTIONS);
            result.resolve(docEntries);
        });

        return result.promise();
    }
Private

_getOffsetsForFunction

docEntries non-nullable Array.<{doc: Document, fileInfo: FileInfo, functions: Array.<offsetStart: number, offsetEnd: number>}>
functionName non-nullable string
rangeResults non-nullable Array.<document: Document, name: string, lineStart: number, lineEnd: number>
Returns: $.Promise
A promise resolved with an array of document ranges to populate a MultiRangeInlineEditor.
    function _getOffsetsForFunction(docEntries, functionName) {
        // Filter for documents that contain the named function
        var result              = new $.Deferred(),
            matchedDocuments    = [],
            rangeResults        = [];

        docEntries.forEach(function (docEntry) {
            // Need to call _.has here since docEntry.functions could have an
            // entry for "hasOwnProperty", which results in an error if trying
            // to invoke docEntry.functions.hasOwnProperty().
            if (_.has(docEntry.functions, functionName)) {
                var functionsInDocument = docEntry.functions[functionName];
                matchedDocuments.push({doc: docEntry.doc, fileInfo: docEntry.fileInfo, functions: functionsInDocument});
            }
        });

        Async.doInParallel(matchedDocuments, function (docEntry) {
            var doc         = docEntry.doc,
                oneResult   = new $.Deferred();

            // doc will be undefined if we hit the cache
            if (!doc) {
                DocumentManager.getDocumentForPath(docEntry.fileInfo.fullPath)
                    .done(function (fetchedDoc) {
                        _computeOffsets(fetchedDoc, functionName, docEntry.functions, rangeResults);
                    })
                    .always(function () {
                        oneResult.resolve();
                    });
            } else {
                _computeOffsets(doc, functionName, docEntry.functions, rangeResults);
                oneResult.resolve();
            }

            return oneResult.promise();
        }).done(function () {
            result.resolve(rangeResults);
        });

        return result.promise();
    }
Private

_readFile

fileInfo non-nullable FileInfo
File to parse
result non-nullable $.Deferred
Deferred to resolve with all functions found and the document
    function _readFile(fileInfo, result) {
        DocumentManager.getDocumentForPath(fileInfo.fullPath)
            .done(function (doc) {
                var allFunctions = _findAllFunctionsInText(doc.getText());

                // Cache the result in the fileInfo object
                fileInfo.JSUtils = {};
                fileInfo.JSUtils.functions = allFunctions;
                fileInfo.JSUtils.timestamp = doc.diskTimestamp;

                result.resolve({doc: doc, functions: allFunctions});
            })
            .fail(function (error) {
                result.reject(error);
            });
    }
Private

_shouldGetFromCache

Determines if the document function cache is up to date.

fileInfo FileInfo
Returns: $.Promise
A promise resolved with true with true when a function cache is available for the document. Resolves with false when there is no cache or the cache is stale.
    function _shouldGetFromCache(fileInfo) {
        var result = new $.Deferred(),
            isChanged = _changedDocumentTracker.isPathChanged(fileInfo.fullPath);

        if (isChanged && fileInfo.JSUtils) {
            // See if it's dirty and in the working set first
            var doc = DocumentManager.getOpenDocumentForPath(fileInfo.fullPath);

            if (doc && doc.isDirty) {
                result.resolve(false);
            } else {
                // If a cache exists, check the timestamp on disk
                var file = FileSystem.getFileForPath(fileInfo.fullPath);

                file.stat(function (err, stat) {
                    if (!err) {
                        result.resolve(fileInfo.JSUtils.timestamp.getTime() === stat.mtime.getTime());
                    } else {
                        result.reject(err);
                    }
                });
            }
        } else {
            // Use the cache if the file did not change and the cache exists
            result.resolve(!isChanged && fileInfo.JSUtils);
        }

        return result.promise();
    }
Public API

findAllMatchingFunctionsInText

Finds all instances of the specified searchName in "text". Returns an Array of Objects with start and end properties.

{!String} text
JS text to search
{!String} searchName
function name to search for
Returns: Array.<{offset:number,functionName:string}>
Array of objects containing the start offset for each matched function name.
    function findAllMatchingFunctionsInText(text, searchName) {
        var allFunctions = _findAllFunctionsInText(text);
        var result = [];
        var lines = text.split("\n");

        _.forEach(allFunctions, function (functions, functionName) {
            if (functionName === searchName || searchName === "*") {
                functions.forEach(function (funcEntry) {
                    var endOffset = _getFunctionEndOffset(text, funcEntry.offsetStart);
                    result.push({
                        name: functionName,
                        label: funcEntry.label,
                        lineStart: StringUtils.offsetToLineNum(lines, funcEntry.offsetStart),
                        lineEnd: StringUtils.offsetToLineNum(lines, endOffset),
                        nameLineStart: funcEntry.location.start.line - 1,
                        nameLineEnd: funcEntry.location.end.line - 1,
                        columnStart: funcEntry.location.start.column,
                        columnEnd: funcEntry.location.end.column
                    });
                });
            }
        });

        return result;
    }

    PerfUtils.createPerfMeasurement("JSUTILS_GET_ALL_FUNCTIONS", "Parallel file search across project");
    PerfUtils.createPerfMeasurement("JSUTILS_REGEXP", "RegExp search for all functions");
    PerfUtils.createPerfMeasurement("JSUTILS_END_OFFSET", "Find end offset for a single matched function");

    exports.findAllMatchingFunctionsInText = findAllMatchingFunctionsInText;
    exports._getFunctionEndOffset = _getFunctionEndOffset; // For testing only
    exports.findMatchingFunctions = findMatchingFunctions;
});
Public API

findMatchingFunctions

Return all functions that have the specified name, searching across all the given files.

functionName non-nullable String
The name to match.
fileInfos non-nullable Array.<File>
The array of files to search.
keepAllFiles optional boolean
If true, don't ignore non-javascript files.
Returns: $.Promise
that will be resolved with an Array of objects containing the source document, start line, and end line (0-based, inclusive range) for each matching function list. Does not addRef() the documents returned in the array.
    function findMatchingFunctions(functionName, fileInfos, keepAllFiles) {
        var result  = new $.Deferred(),
            jsFiles = [];

        if (!keepAllFiles) {
            // Filter fileInfos for .js files
            jsFiles = fileInfos.filter(function (fileInfo) {
                return FileUtils.getFileExtension(fileInfo.fullPath).toLowerCase() === "js";
            });
        } else {
            jsFiles = fileInfos;
        }

        // RegExp search (or cache lookup) for all functions in the project
        _getFunctionsInFiles(jsFiles).done(function (docEntries) {
            // Compute offsets for all matched functions
            _getOffsetsForFunction(docEntries, functionName).done(function (rangeResults) {
                result.resolve(rangeResults);
            });
        });

        return result.promise();
    }