Поиск ошибок brackets

Manages linters and other code inspections on a per-language basis. Provides a UI and status indicator for
the resulting errors/warnings.

Currently, inspection providers are only invoked on the current file and only when it is opened, switched to,
or saved. But in the future, inspectors may be invoked as part of a global scan, at intervals while typing, etc.
Currently, results are only displayed in a bottom panel list and in a status bar icon. But in the future,
results may also be displayed inline in the editor (as gutter markers, squiggly underlines, etc.).
In the future, support may also be added for error/warning providers that cannot process a single file at a time
(e.g. a full-project compiler).

Private

$problemsPanel

Type

$.Element

    var $problemsPanel;

Private

$problemsPanelTable

Type

$.Element

    var $problemsPanelTable;

PREF_ENABLED

Constants for the preferences defined in this file.

    var PREF_ENABLED            = "enabled",
        PREF_COLLAPSED          = "collapsed",
        PREF_ASYNC_TIMEOUT      = "asyncTimeout",
        PREF_PREFER_PROVIDERS   = "prefer",
        PREF_PREFERRED_ONLY     = "usePreferredOnly";

    var prefs = PreferencesManager.getExtensionPrefs("linting");

Public API

Type

Values for problem’s ‘type’ property

    var Type = {

Private

_collapsed

When collapsed, the errors panel is closed but the status bar icon is kept up to date.

Type

boolean

    var _collapsed = false;

Private

_currentPromise

Promise of the returned by the last call to inspectFile or null if linting is disabled. Used to prevent any stale promises
to cause updates of the UI.

Type

$.Promise

    var _currentPromise = null;

Private

_enabled

When disabled, the errors panel is closed and the status bar icon is grayed out.
Takes precedence over _collapsed.

Type

boolean

    var _enabled = false;

Private

_gotoEnabled

Type

boolean

    var _gotoEnabled = false;

Private

_hasErrors

Type

boolean

    var _hasErrors;

Private

_providers

Type

{languageId:string, Array.<{name:string, scanFileAsync:?function(string, string):!{$.Promise}, scanFile:?function(string, string):Object}>}

    var _providers = {};

Public API

getProviderIDsForLanguage

Returns an array of the IDs of providers registered for a specific language

languageId
non-nullable
string

Returns: Array.<string>

Names of registered providers.

    function getProviderIDsForLanguage(languageId) {
        if (!_providers[languageId]) {
            return [];
        }
        return _providers[languageId].map(function (provider) {
            return provider.name;
        });
    }

getProvidersForLanguageId

Returns a list of providers registered for given languageId through register function

    function getProvidersForLanguageId(languageId) {
        var result = [];
        if (_providers[languageId]) {
            result = result.concat(_providers[languageId]);
        }
        if (_providers['*']) {
            result = result.concat(_providers['*']);
        }
        return result;
    }

Public API

getProvidersForPath

Returns a list of provider for given file path, if available.
Decision is made depending on the file extension.

filePath
non-nullable
string

Returns: Array.<{name:string,scanFileAsync:?function(string,string):!{$.Promise},scanFile:?function(string,string):?{errors:!Array,aborted:boolean}}>

    function getProvidersForPath(filePath) {
        var language            = LanguageManager.getLanguageForPath(filePath).getId(),
            context             = PreferencesManager._buildContext(filePath, language),
            installedProviders  = getProvidersForLanguageId(language),
            preferredProviders,

            prefPreferredProviderNames  = prefs.get(PREF_PREFER_PROVIDERS, context),
            prefPreferredOnly           = prefs.get(PREF_PREFERRED_ONLY, context),

            providers;

        if (prefPreferredProviderNames && prefPreferredProviderNames.length) {
            if (typeof prefPreferredProviderNames === "string") {
                prefPreferredProviderNames = [prefPreferredProviderNames];
            }
            preferredProviders = prefPreferredProviderNames.reduce(function (result, key) {
                var provider = _.find(installedProviders, {name: key});
                if (provider) {
                    result.push(provider);
                }
                return result;
            }, []);
            if (prefPreferredOnly) {
                providers = preferredProviders;
            } else {
                providers = _.union(preferredProviders, installedProviders);
            }
        } else {
            providers = installedProviders;
        }
        return providers;
    }

handleGotoFirstProblem

Command to go to the first Problem

    function handleGotoFirstProblem() {
        run();
        if (_gotoEnabled) {
            $problemsPanel.find("tr:not(.inspector-section)").first().trigger("click");
        }
    }

    // Register command handlers
    CommandManager.register(Strings.CMD_VIEW_TOGGLE_INSPECTION, Commands.VIEW_TOGGLE_INSPECTION,        toggleEnabled);
    CommandManager.register(Strings.CMD_GOTO_FIRST_PROBLEM,     Commands.NAVIGATE_GOTO_FIRST_PROBLEM,   handleGotoFirstProblem);

    // Register preferences
    prefs.definePreference(PREF_ENABLED, "boolean", brackets.config["linting.enabled_by_default"], {
        description: Strings.DESCRIPTION_LINTING_ENABLED
    })
        .on("change", function (e, data) {
            toggleEnabled(prefs.get(PREF_ENABLED), true);
        });

    prefs.definePreference(PREF_COLLAPSED, "boolean", false, {
        description: Strings.DESCRIPTION_LINTING_COLLAPSED
    })
        .on("change", function (e, data) {
            toggleCollapsed(prefs.get(PREF_COLLAPSED), true);
        });

    prefs.definePreference(PREF_ASYNC_TIMEOUT, "number", 10000, {
        description: Strings.DESCRIPTION_ASYNC_TIMEOUT
    });

    prefs.definePreference(PREF_PREFER_PROVIDERS, "array", [], {
        description: Strings.DESCRIPTION_LINTING_PREFER,
        valueType: "string"
    });

    prefs.definePreference(PREF_PREFERRED_ONLY, "boolean", false, {
        description: Strings.DESCRIPTION_USE_PREFERED_ONLY
    });

    // Initialize items dependent on HTML DOM
    AppInit.htmlReady(function () {
        // Create bottom panel to list error details
        var panelHtml = Mustache.render(PanelTemplate, Strings);
        WorkspaceManager.createBottomPanel("errors", $(panelHtml), 100);
        $problemsPanel = $("#problems-panel");

        var $selectedRow;
        $problemsPanelTable = $problemsPanel.find(".table-container")
            .on("click", "tr", function (e) {
                if ($selectedRow) {
                    $selectedRow.removeClass("selected");
                }

                $selectedRow  = $(e.currentTarget);
                $selectedRow.addClass("selected");

                // This is a inspector title row, expand/collapse on click
                if ($selectedRow.hasClass("inspector-section")) {
                    var $triangle = $(".disclosure-triangle", $selectedRow);
                    var isExpanded = $triangle.hasClass("expanded");

                    // Clicking the inspector title section header collapses/expands result rows
                    if (isExpanded) {
                        $selectedRow.nextUntil(".inspector-section").addClass("forced-hidden");
                    } else {
                        $selectedRow.nextUntil(".inspector-section").removeClass("forced-hidden");
                    }
                    $triangle.toggleClass("expanded");

                    var providerName = $selectedRow.find("input[type='hidden']").val();
                    prefs.set(providerName + ".collapsed", !isExpanded);
                    prefs.save();
                } else {
                    // This is a problem marker row, show the result on click
                    // Grab the required position data
                    var lineTd    = $selectedRow.find(".line-number");
                    var line      = parseInt(lineTd.text(), 10) - 1;  // convert friendlyLine back to pos.line
                    // if there is no line number available, don't do anything
                    if (!isNaN(line)) {
                        var character = lineTd.data("character");

                        var editor = EditorManager.getCurrentFullEditor();
                        editor.setCursorPos(line, character, true);
                        MainViewManager.focusActivePane();
                    }
                }
            });

        $("#problems-panel .close").click(function () {
            toggleCollapsed(true);
        });

        // Status bar indicator - icon & tooltip updated by run()
        var statusIconHtml = Mustache.render("<div id=\"status-inspection\">&nbsp;</div>", Strings);
        StatusBar.addIndicator(INDICATOR_ID, $(statusIconHtml), true, "", "", "status-indent");

        $("#status-inspection").click(function () {
            // Clicking indicator toggles error panel, if any errors in current file
            if (_hasErrors) {
                toggleCollapsed();
            }
        });

        // Set initial UI state
        toggleEnabled(prefs.get(PREF_ENABLED), true);
        toggleCollapsed(prefs.get(PREF_COLLAPSED), true);
    });

    // Testing
    exports._unregisterAll          = _unregisterAll;
    exports._PREF_ASYNC_TIMEOUT     = PREF_ASYNC_TIMEOUT;
    exports._PREF_PREFER_PROVIDERS  = PREF_PREFER_PROVIDERS;
    exports._PREF_PREFERRED_ONLY    = PREF_PREFERRED_ONLY;

    // Public API
    exports.register                    = register;
    exports.Type                        = Type;
    exports.toggleEnabled               = toggleEnabled;
    exports.inspectFile                 = inspectFile;
    exports.requestRun                  = run;
    exports.getProvidersForPath         = getProvidersForPath;
    exports.getProviderIDsForLanguage   = getProviderIDsForLanguage;
});

Public API

inspectFile

file
non-nullable
File

File that will be inspected for errors.

providerList
nullable
Array.<{name:string, scanFileAsync:?function(string, string):!{$.Promise}, scanFile:?function(string, string):?{errors:!Array, aborted:boolean}}>

Returns: $.Promise

a jQuery promise that will be resolved with ?Array.<{provider:Object, result: ?{errors:!Array, aborted:boolean}}>

    function inspectFile(file, providerList) {
        var response = new $.Deferred(),
            results = [];

        providerList = providerList || getProvidersForPath(file.fullPath);

        if (!providerList.length) {
            response.resolve(null);
            return response.promise();
        }

        DocumentManager.getDocumentText(file)
            .done(function (fileText) {
                var perfTimerInspector = PerfUtils.markStart("CodeInspection:\t" + file.fullPath),
                    masterPromise;

                masterPromise = Async.doInParallel(providerList, function (provider) {
                    var perfTimerProvider = PerfUtils.markStart("CodeInspection '" + provider.name + "':\t" + file.fullPath),
                        runPromise = new $.Deferred();

                    runPromise.done(function (scanResult) {
                        results.push({provider: provider, result: scanResult});
                    });

                    if (provider.scanFileAsync) {
                        window.setTimeout(function () {
                            // timeout error
                            var errTimeout = {
                                pos: { line: -1, col: 0},
                                message: StringUtils.format(Strings.LINTER_TIMED_OUT, provider.name, prefs.get(PREF_ASYNC_TIMEOUT)),
                                type: Type.ERROR
                            };
                            runPromise.resolve({errors: [errTimeout]});
                        }, prefs.get(PREF_ASYNC_TIMEOUT));
                        provider.scanFileAsync(fileText, file.fullPath)
                            .done(function (scanResult) {
                                PerfUtils.addMeasurement(perfTimerProvider);
                                runPromise.resolve(scanResult);
                            })
                            .fail(function (err) {
                                PerfUtils.finalizeMeasurement(perfTimerProvider);
                                var errError = {
                                    pos: {line: -1, col: 0},
                                    message: StringUtils.format(Strings.LINTER_FAILED, provider.name, err),
                                    type: Type.ERROR
                                };
                                console.error("[CodeInspection] Provider " + provider.name + " (async) failed: " + err);
                                runPromise.resolve({errors: [errError]});
                            });
                    } else {
                        try {
                            var scanResult = provider.scanFile(fileText, file.fullPath);
                            PerfUtils.addMeasurement(perfTimerProvider);
                            runPromise.resolve(scanResult);
                        } catch (err) {
                            PerfUtils.finalizeMeasurement(perfTimerProvider);
                            var errError = {
                                pos: {line: -1, col: 0},
                                message: StringUtils.format(Strings.LINTER_FAILED, provider.name, err),
                                type: Type.ERROR
                            };
                            console.error("[CodeInspection] Provider " + provider.name + " (sync) threw an error: " + err);
                            runPromise.resolve({errors: [errError]});
                        }
                    }
                    return runPromise.promise();

                }, false);

                masterPromise.then(function () {
                    // sync async may have pushed results in different order, restore the original order
                    results.sort(function (a, b) {
                        return providerList.indexOf(a.provider) - providerList.indexOf(b.provider);
                    });
                    PerfUtils.addMeasurement(perfTimerInspector);
                    response.resolve(results);
                });

            })
            .fail(function (err) {
                console.error("[CodeInspection] Could not read file for inspection: " + file.fullPath);
                response.reject(err);
            });

        return response.promise();
    }

Public API

register

languageId
string

provider
{name:string,scanFileAsync:?function(string,string):!{$.Promise},scanFile:?function(string,string):?{errors:!Array,aborted:boolean}}

Each error is: { pos:{line,ch}, endPos:?{line,ch}, message:string, type:?Type } If type is unspecified, Type.WARNING is assumed. If no errors found, return either null or an object with a zero-length `errors` array.

    function register(languageId, provider) {
        if (!_providers[languageId]) {
            _providers[languageId] = [];
        } else {
            // Check if provider with same name exists for the given language
            // If yes, remove the provider before inserting the most recently loaded one
            var indexOfProvider = _.findIndex(_providers[languageId], function(entry) { return entry.name === provider.name; });
            if (indexOfProvider !== -1) {
                _providers[languageId].splice(indexOfProvider, 1);
            }
        }

        _providers[languageId].push(provider);

        run();  // in case a file of this type is open currently
    }

run

Run inspector applicable to current document. Updates status bar indicator and refreshes error list in
bottom panel. Does not run if inspection is disabled or if a providerName is given and does not
match the current doc’s provider name.

providerName
nullable
string

name of the provider that is requesting a run

    function run() {
        if (!_enabled) {
            _hasErrors = false;
            _currentPromise = null;
            Resizer.hide($problemsPanel);
            StatusBar.updateIndicator(INDICATOR_ID, true, "inspection-disabled", Strings.LINT_DISABLED);
            setGotoEnabled(false);
            return;
        }

        var currentDoc = DocumentManager.getCurrentDocument(),
            providerList = currentDoc && getProvidersForPath(currentDoc.file.fullPath);

        if (providerList && providerList.length) {
            var numProblems = 0;
            var aborted = false;
            var allErrors = [];
            var html;
            var providersReportingProblems = [];

            // run all the providers registered for this file type
            (_currentPromise = inspectFile(currentDoc.file, providerList)).then(function (results) {
                // check if promise has not changed while inspectFile was running
                if (this !== _currentPromise) {
                    return;
                }

                // how many errors in total?
                var errors = results.reduce(function (a, item) { return a + (item.result ? item.result.errors.length : 0); }, 0);

                _hasErrors = Boolean(errors);

                if (!errors) {
                    Resizer.hide($problemsPanel);

                    var message = Strings.NO_ERRORS_MULTIPLE_PROVIDER;
                    if (providerList.length === 1) {
                        message = StringUtils.format(Strings.NO_ERRORS, providerList[0].name);
                    }

                    StatusBar.updateIndicator(INDICATOR_ID, true, "inspection-valid", message);

                    setGotoEnabled(false);
                    return;
                }

                var perfTimerDOM = PerfUtils.markStart("ProblemsPanel render:\t" + currentDoc.file.fullPath);

                // Augment error objects with additional fields needed by Mustache template
                results.forEach(function (inspectionResult) {
                    var provider = inspectionResult.provider;
                    var isExpanded = prefs.get(provider.name + ".collapsed") !== false;

                    if (inspectionResult.result) {
                        inspectionResult.result.errors.forEach(function (error) {
                            // some inspectors don't always provide a line number or report a negative line number
                            if (!isNaN(error.pos.line) &&
                                    (error.pos.line + 1) > 0 &&
                                    (error.codeSnippet = currentDoc.getLine(error.pos.line)) !== undefined) {
                                error.friendlyLine = error.pos.line + 1;
                                error.codeSnippet = error.codeSnippet.substr(0, 175);  // limit snippet width
                            }

                            if (error.type !== Type.META) {
                                numProblems++;
                            }

                            // Hide the errors when the provider is collapsed.
                            error.display = isExpanded ? "" : "forced-hidden";
                        });

                        // if the code inspector was unable to process the whole file, we keep track to show a different status
                        if (inspectionResult.result.aborted) {
                            aborted = true;
                        }

                        if (inspectionResult.result.errors.length) {
                            allErrors.push({
                                isExpanded:   isExpanded,
                                providerName: provider.name,
                                results:      inspectionResult.result.errors
                            });

                            providersReportingProblems.push(provider);
                        }
                    }
                });

                // Update results table
                html = Mustache.render(ResultsTemplate, {reportList: allErrors});

                $problemsPanelTable
                    .empty()
                    .append(html)
                    .scrollTop(0);  // otherwise scroll pos from previous contents is remembered

                if (!_collapsed) {
                    Resizer.show($problemsPanel);
                }

                updatePanelTitleAndStatusBar(numProblems, providersReportingProblems, aborted);
                setGotoEnabled(true);

                PerfUtils.addMeasurement(perfTimerDOM);
            });

        } else {
            // No provider for current file
            _hasErrors = false;
            _currentPromise = null;
            Resizer.hide($problemsPanel);
            var language = currentDoc && LanguageManager.getLanguageForPath(currentDoc.file.fullPath);
            if (language) {
                StatusBar.updateIndicator(INDICATOR_ID, true, "inspection-disabled", StringUtils.format(Strings.NO_LINT_AVAILABLE, language.getName()));
            } else {
                StatusBar.updateIndicator(INDICATOR_ID, true, "inspection-disabled", Strings.NOTHING_TO_LINT);
            }
            setGotoEnabled(false);
        }
    }

setGotoEnabled

Enable or disable the «Go to First Error» command

gotoEnabled
boolean

Whether it is enabled.

    function setGotoEnabled(gotoEnabled) {
        CommandManager.get(Commands.NAVIGATE_GOTO_FIRST_PROBLEM).setEnabled(gotoEnabled);
        _gotoEnabled = gotoEnabled;
    }

    function _unregisterAll() {
        _providers = {};
    }

toggleCollapsed

Toggle the collapsed state for the panel. This explicitly collapses the panel (as opposed to
the auto collapse due to files with no errors & filetypes with no provider). When explicitly
collapsed, the panel will not reopen automatically on switch files or save.

collapsed
nullable
boolean

Collapsed state. If omitted, the state is toggled.

doNotSave
nullable
boolean

true if the preference should not be saved to user settings. This is generally for events triggered by project-level settings.

    function toggleCollapsed(collapsed, doNotSave) {
        if (collapsed === undefined) {
            collapsed = !_collapsed;
        }

        if (collapsed === _collapsed) {
            return;
        }

        _collapsed = collapsed;
        if (!doNotSave) {
            prefs.set(PREF_COLLAPSED, _collapsed);
            prefs.save();
        }

        if (_collapsed) {
            Resizer.hide($problemsPanel);
        } else {
            if (_hasErrors) {
                Resizer.show($problemsPanel);
            }
        }
    }

Public API

toggleEnabled

Enable or disable all inspection.

enabled
nullable
boolean

Enabled state. If omitted, the state is toggled.

doNotSave
nullable
boolean

true if the preference should not be saved to user settings. This is generally for events triggered by project-level settings.

    function toggleEnabled(enabled, doNotSave) {
        if (enabled === undefined) {
            enabled = !_enabled;
        }

        // Take no action when there is no change.
        if (enabled === _enabled) {
            return;
        }

        _enabled = enabled;

        CommandManager.get(Commands.VIEW_TOGGLE_INSPECTION).setChecked(_enabled);
        updateListeners();
        if (!doNotSave) {
            prefs.set(PREF_ENABLED, _enabled);
            prefs.save();
        }

        // run immediately
        run();
    }

updateListeners

Update DocumentManager listeners.

    function updateListeners() {
        if (_enabled) {
            // register our event listeners
            MainViewManager
                .on("currentFileChange.codeInspection", function () {
                    run();
                });
            DocumentManager
                .on("currentDocumentLanguageChanged.codeInspection", function () {
                    run();
                })
                .on("documentSaved.codeInspection documentRefreshed.codeInspection", function (event, document) {
                    if (document === DocumentManager.getCurrentDocument()) {
                        run();
                    }
                });
        } else {
            DocumentManager.off(".codeInspection");
            MainViewManager.off(".codeInspection");
        }
    }

updatePanelTitleAndStatusBar

Update the title of the problem panel and the tooltip of the status bar icon. The title and the tooltip will
change based on the number of problems reported and how many provider reported problems.

numProblems
Number

total number of problems across all providers

providersReportingProblems
Array.<{name:string,scanFileAsync:?function(string,string):!{$.Promise},scanFile:?function(string,string):Object}>

providers that reported problems

aborted
boolean

true if any provider returned a result with the ‘aborted’ flag set

    function updatePanelTitleAndStatusBar(numProblems, providersReportingProblems, aborted) {
        var message, tooltip;

        if (providersReportingProblems.length === 1) {
            // don't show a header if there is only one provider available for this file type
            $problemsPanelTable.find(".inspector-section").hide();
            $problemsPanelTable.find("tr").removeClass("forced-hidden");

            if (numProblems === 1 && !aborted) {
                message = StringUtils.format(Strings.SINGLE_ERROR, providersReportingProblems[0].name);
            } else {
                if (aborted) {
                    numProblems += "+";
                }

                message = StringUtils.format(Strings.MULTIPLE_ERRORS, providersReportingProblems[0].name, numProblems);
            }
        } else if (providersReportingProblems.length > 1) {
            $problemsPanelTable.find(".inspector-section").show();

            if (aborted) {
                numProblems += "+";
            }

            message = StringUtils.format(Strings.ERRORS_PANEL_TITLE_MULTIPLE, numProblems);
        } else {
            return;
        }

        $problemsPanel.find(".title").text(message);
        tooltip = StringUtils.format(Strings.STATUSBAR_CODE_INSPECTION_TOOLTIP, message);
        StatusBar.updateIndicator(INDICATOR_ID, true, "inspection-errors", tooltip);
    }

CodeHintManager Overview:

The CodeHintManager mediates the interaction between the editor and a
collection of hint providers. If hints are requested explicitly by the
user, then the providers registered for the current language are queried
for their ability to provide hints in order of descending priority by
way their hasHints methods. Character insertions may also constitute an
implicit request for hints; consequently, providers for the current
language are also queried on character insertion for both their ability to
provide hints and also for the suitability of providing implicit hints
in the given editor context.

Once a provider responds affirmatively to a request for hints, the
manager begins a hinting session with that provider, begins to query
that provider for hints by way of its getHints method, and opens the
hint list window. The hint list is kept open for the duration of the
current session. The manager maintains the session until either:

1. the provider gives a null response to a request for hints;
2. a deferred response to getHints fails to resolve;
3. the user explicitly dismisses the hint list window;
4. the editor is closed or becomes inactive; or
5. the editor undergoes a «complex» change, e.g., a multi-character
   insertion, deletion or navigation.

Single-character insertions, deletions or navigations may not
invalidate the current session; in which case, each such change
precipitates a successive call to getHints.

If the user selects a hint from the rendered hint list then the
provider is responsible for inserting the hint into the editor context
for the current session by way of its insertHint method. The provider
may use the return value of insertHint to request that an additional
explicit hint request be triggered, potentially beginning a new
session.

CodeHintProvider Overview:

A code hint provider should implement the following three functions:

• CodeHintProvider.hasHints(editor, implicitChar)
• CodeHintProvider.getHints(implicitChar)
• CodeHintProvider.insertHint(hint)

The behavior of these three functions is described in detail below.

CodeHintProvider.hasHints(editor, implicitChar)

The method by which a provider indicates intent to provide hints for a
given editor. The manager calls this method both when hints are
explicitly requested (via, e.g., Ctrl-Space) and when they may be
implicitly requested as a result of character insertion in the editor.
If the provider responds negatively then the manager may query other
providers for hints. Otherwise, a new hinting session begins with this
provider, during which the manager may repeatedly query the provider
for hints via the getHints method. Note that no other providers will be
queried until the hinting session ends.

The implicitChar parameter is used to determine whether the hinting
request is explicit or implicit. If the string is null then hints were
explicitly requested and the provider should reply based on whether it
is possible to return hints for the given editor context. Otherwise,
the string contains just the last character inserted into the editor’s
document and the request for hints is implicit. In this case, the
provider should determine whether it is both possible and appropriate
to show hints. Because implicit hints can be triggered by every
character insertion, hasHints may be called frequently; consequently,
the provider should endeavor to return a value as quickly as possible.

Because calls to hasHints imply that a hinting session is about to
begin, a provider may wish to clean up cached data from previous
sessions in this method. Similarly, if the provider returns true, it
may wish to prepare to cache data suitable for the current session. In
particular, it should keep a reference to the editor object so that it
can access the editor in future calls to getHints and insertHints.

param {Editor} editor
A non-null editor object for the active window.

param {string} implicitChar
Either null, if the hinting request was explicit, or a single character
that represents the last insertion and that indicates an implicit
hinting request.

return {boolean}
Determines whether the current provider is able to provide hints for
the given editor context and, in case implicitChar is non- null,
whether it is appropriate to do so.

CodeHintProvider.getHints(implicitChar)

The method by which a provider provides hints for the editor context
associated with the current session. The getHints method is called only
if the provider asserted its willingness to provide hints in an earlier
call to hasHints. The provider may return null or false, which indicates
that the manager should end the current hinting session and close the hint
list window; or true, which indicates that the manager should end the
current hinting session but immediately attempt to begin a new hinting
session by querying registered providers. Otherwise, the provider should
return a response object that contains the following properties:

1. hints, a sorted array hints that the provider could later insert
   into the editor;
2. match, a string that the manager may use to emphasize substrings of
   hints in the hint list (case-insensitive); and
3. selectInitial, a boolean that indicates whether or not the
   first hint in the list should be selected by default.
4. handleWideResults, a boolean (or undefined) that indicates whether
   to allow result string to stretch width of display.

If the array of
hints is empty, then the manager will render an empty list, but the
hinting session will remain open and the value of the selectInitial
property is irrelevant.

Alternatively, the provider may return a jQuery.Deferred object
that resolves with an object with the structure described above. In
this case, the manager will initially render the hint list window with
a throbber and will render the actual list once the deferred object
resolves to a response object. If a hint list has already been rendered
(from an earlier call to getHints), then the old list will continue
to be displayed until the new deferred has resolved.

Both the manager and the provider can reject the deferred object. The
manager will reject the deferred if the editor changes state (e.g., the
user types a character) or if the hinting session ends (e.g., the user
explicitly closes the hints by pressing escape). The provider can use
this event to, e.g., abort an expensive computation. Consequently, the
provider may assume that getHints will not be called again until the
deferred object from the current call has resolved or been rejected. If
the provider rejects the deferred, the manager will end the hinting
session.

The getHints method may be called by the manager repeatedly during a
hinting session. Providers may wish to cache information for efficiency
that may be useful throughout these sessions. The same editor context
will be used throughout a session, and will only change during the
session as a result of single-character insertions, deletions and
cursor navigations. The provider may assume that, throughout the
lifetime of the session, the getHints method will be called exactly
once for each such editor change. Consequently, the provider may also
assume that the document will not be changed outside of the editor
during a session.

param {string} implicitChar
Either null, if the request to update the hint list was a result of
navigation, or a single character that represents the last insertion.

return {jQuery.Deferred|{
     hints: Array.<string|jQueryObject>,
     match: string,
     selectInitial: boolean,
     handleWideResults: boolean}}

Null if the provider wishes to end the hinting session. Otherwise, a
response object, possibly deferred, that provides 1. a sorted array
hints that consists either of strings or jQuery objects; 2. a string
match, possibly null, that is used by the manager to emphasize
matching substrings when rendering the hint list; and 3. a boolean that
indicates whether the first result, if one exists, should be selected
by default in the hint list window. If match is non-null, then the
hints should be strings.

If the match is null, the manager will not
attempt to emphasize any parts of the hints when rendering the hint
list; instead the provider may return strings or jQuery objects for
which emphasis is self-contained. For example, the strings may contain
substrings that wrapped in bold tags. In this way, the provider can
choose to let the manager handle emphasis for the simple and common case
of prefix matching, or can provide its own emphasis if it wishes to use
a more sophisticated matching algorithm.

CodeHintProvider.insertHint(hint)

The method by which a provider inserts a hint into the editor context
associated with the current session. The provider may assume that the
given hint was returned by the provider in some previous call in the
current session to getHints, but not necessarily the most recent call.
After the insertion has been performed, the current hinting session is
closed. The provider should return a boolean value to indicate whether
or not the end of the session should be immediately followed by a new
explicit hinting request, which may result in a new hinting session
being opened with some provider, but not necessarily the current one.

param {string} hint
The hint to be inserted into the editor context for the current session.

return {boolean}
Indicates whether the manager should follow hint insertion with an
explicit hint request.

CodeHintProvider.insertHintOnTab

type {?boolean} insertHintOnTab
Indicates whether the CodeHintManager should request that the provider of
the current session insert the currently selected hint on tab key events,
or if instead a tab character should be inserted into the editor. If omitted,
the fallback behavior is determined by the CodeHintManager. The default
behavior is to insert a tab character, but this can be changed with the
insertHintOnTab Preference.

Private

_endSession

End the current hinting session

    function _endSession() {
        if (!hintList) {
            return;
        }
        hintList.close();
        hintList = null;
        codeHintOpened = false;
        keyDownEditor = null;
        sessionProvider = null;
        sessionEditor = null;
        if (deferredHints) {
            deferredHints.reject();
            deferredHints = null;
        }
    }

Private
Public API

_getCodeHintList

Expose CodeHintList for unit testing

    function _getCodeHintList() {
        return hintList;
    }

    function activeEditorChangeHandler(event, current, previous) {
        if (current) {
            current.on("editorChange", _handleChange);
            current.on("keydown",  _handleKeydownEvent);
            current.on("keypress", _handleKeypressEvent);
            current.on("keyup",    _handleKeyupEvent);
            current.on("cursorActivity", _handleCursorActivity);
        }

        if (previous) {
            //Removing all old Handlers
            previous.off("editorChange", _handleChange);
            previous.off("keydown",  _handleKeydownEvent);
            previous.off("keypress", _handleKeypressEvent);
            previous.off("keyup",    _handleKeyupEvent);
            previous.off("cursorActivity", _handleCursorActivity);
        }
    }

    activeEditorChangeHandler(null, EditorManager.getActiveEditor(), null);

    EditorManager.on("activeEditorChange", activeEditorChangeHandler);
 
    // Dismiss code hints before executing any command other than showing code hints since the command
    // may make the current hinting session irrevalent after execution.
    // For example, when the user hits Ctrl+K to open Quick Doc, it is
    // pointless to keep the hint list since the user wants to view the Quick Doc
    CommandManager.on("beforeExecuteCommand", function (event, commandId) {
        if (commandId !== Commands.SHOW_CODE_HINTS) {
            _endSession();
        }
    });

    CommandManager.register(Strings.CMD_SHOW_CODE_HINTS, Commands.SHOW_CODE_HINTS, _startNewSession);

    exports._getCodeHintList        = _getCodeHintList;
    exports._removeHintProvider     = _removeHintProvider;

    // Define public API
    exports.isOpen                  = isOpen;
    exports.registerHintProvider    = registerHintProvider;
    exports.hasValidExclusion       = hasValidExclusion;
});

Private

_getProvidersForLanguageId

Return the array of hint providers for the given language id.
This gets called (potentially) on every keypress. So, it should be fast.

languageId
non-nullable
string

Returns: ?Array.<{provider: Object,priority: number}>

    function _getProvidersForLanguageId(languageId) {
        var providers = hintProviders[languageId] || hintProviders.all;

        // Exclude providers that are explicitly disabled in the preferences.
        // All code hint providers that do not have their constructor
        // names listed in the preferences are enabled by default.
        return providers.filter(function (provider) {
            var prefKey = "codehint." + provider.provider.constructor.name;
            return PreferencesManager.get(prefKey) !== false;
        });
    }

    var _beginSession;

Private

_handleChange

Start a new implicit hinting session, or update the existing hint list.
Called by the editor after handleKeyEvent, which is responsible for setting
the lastChar.

event
Event

editor
Editor

changeList
{from: Pos,to: Pos,text: Array,origin: string}

    function _handleChange(event, editor, changeList) {
        if (lastChar && editor === keyDownEditor) {
            keyDownEditor = null;
            if (_inSession(editor)) {
                var charToRetest = lastChar;
                _updateHintList();

                // _updateHintList() may end a hinting session and clear lastChar, but a
                // different provider may want to start a new session with the same character.
                // So check whether current provider terminates the current hinting
                // session. If so, then restore lastChar and restart a new session.
                if (!_inSession(editor)) {
                    lastChar = charToRetest;
                    _beginSession(editor);
                }
            } else {
                _beginSession(editor);
            }

            // Pending Text is used in hintList._keydownHook()
            if (hintList && changeList[0] && changeList[0].text.length && changeList[0].text[0].length) {
                var expectedLength = editor.getCursorPos().ch - changeList[0].from.ch,
                    newText = changeList[0].text[0];
                // We may get extra text in newText since some features like auto
                // close braces can append some text automatically.
                // See https://github.com/adobe/brackets/issues/6345#issuecomment-32548064
                // as an example of this scenario.
                if (newText.length > expectedLength) {
                    // Strip off the extra text before calling removePendingText.
                    newText = newText.substr(0, expectedLength);
                }
                hintList.removePendingText(newText);
            }
        }
    }

Private

_handleCursorActivity

Handle a selection change event in the editor. If the selection becomes a
multiple selection, end our current session.

event
BracketsEvent

editor
Editor

    function _handleCursorActivity(event, editor) {
        if (_inSession(editor)) {
            if (editor.getSelections().length > 1) {
                _endSession();
            }
        }
    }

Private

_handleKeydownEvent

jqEvent
Event

editor
Editor

event
KeyboardEvent

    function _handleKeydownEvent(jqEvent, editor, event) {
        keyDownEditor = editor;
        if (!(event.ctrlKey || event.altKey || event.metaKey) &&
                (event.keyCode === KeyEvent.DOM_VK_ENTER ||
                 event.keyCode === KeyEvent.DOM_VK_RETURN ||
                 event.keyCode === KeyEvent.DOM_VK_TAB)) {
            lastChar = String.fromCharCode(event.keyCode);
        }
    }
    function _handleKeypressEvent(jqEvent, editor, event) {
        keyDownEditor = editor;

        // Last inserted character, used later by handleChange
        lastChar = String.fromCharCode(event.charCode);

        // Pending Text is used in hintList._keydownHook()
        if (hintList) {
            hintList.addPendingText(lastChar);
        }
    }
    function _handleKeyupEvent(jqEvent, editor, event) {
        keyDownEditor = editor;
        if (_inSession(editor)) {
          if (event.keyCode === KeyEvent.DOM_VK_HOME || 
                  event.keyCode === KeyEvent.DOM_VK_END) {
                _endSession();
            } else if (event.keyCode === KeyEvent.DOM_VK_LEFT ||
                       event.keyCode === KeyEvent.DOM_VK_RIGHT ||
                       event.keyCode === KeyEvent.DOM_VK_BACK_SPACE) {
                // Update the list after a simple navigation.
                // We do this in "keyup" because we want the cursor position to be updated before
                // we redraw the list.
                _updateHintList();
            } else if (event.ctrlKey && event.keyCode === KeyEvent.DOM_VK_SPACE) {
                _updateHintList(event);
            }
        }
    }

Private

_inSession

editor
Editor

Returns: boolean

    function _inSession(editor) {
        if (sessionEditor) {
            if (sessionEditor === editor &&
                    (hintList.isOpen() ||
                     (deferredHints && deferredHints.state() === "pending"))) {
                return true;
            } else {
                // the editor has changed
                _endSession();
            }
        }
        return false;
    }

Private

_providerSort

Comparator to sort providers from high to low priority

    function _providerSort(a, b) {
        return b.priority - a.priority;
    }

Private
Public API

_removeHintProvider

provider
non-nullable
CodeHintProvider

Code hint provider to remove

targetLanguageId
optional
(string, Array.<string>)

Optional set of language IDs for languages to remove the provider for. Defaults to all languages.

    function _removeHintProvider(provider, targetLanguageId) {
        var index,
            providers,
            targetLanguageIdArr;

        if (Array.isArray(targetLanguageId)) {
            targetLanguageIdArr = targetLanguageId;
        } else if (targetLanguageId) {
            targetLanguageIdArr = [targetLanguageId];
        } else {
            targetLanguageIdArr = Object.keys(hintProviders);
        }

        targetLanguageIdArr.forEach(function (languageId) {
            providers = hintProviders[languageId];

            for (index = 0; index < providers.length; index++) {
                if (providers[index].provider === provider) {
                    providers.splice(index, 1);
                    break;
                }
            }
        });
    }

Private

_startNewSession

Explicitly start a new session. If we have an existing session,
then close the current one and restart a new one.

editor
Editor

    function _startNewSession(editor) {
        if (isOpen()) {
            return;
        }

        if (!editor) {
            editor = EditorManager.getFocusedEditor();
        }
        if (editor) {
            lastChar = null;
            if (_inSession(editor)) {
                _endSession();
            }

            // Begin a new explicit session
            _beginSession(editor);
        }
    }

Private

_updateHintList

    function _updateHintList(callMoveUpEvent) {

        callMoveUpEvent = typeof callMoveUpEvent === "undefined" ? false : callMoveUpEvent;

        if (deferredHints) {
            deferredHints.reject();
            deferredHints = null;
        }

        if (callMoveUpEvent) {
            return hintList.callMoveUp(callMoveUpEvent);
        }

        var response = sessionProvider.getHints(lastChar);
        lastChar = null;

        if (!response) {
            // the provider wishes to close the session
            _endSession();
        } else {
            // if the response is true, end the session and begin another
            if (response === true) {
                var previousEditor = sessionEditor;

                _endSession();
                _beginSession(previousEditor);
            } else if (response.hasOwnProperty("hints")) { // a synchronous response
                if (hintList.isOpen()) {
                    // the session is open
                    hintList.update(response);
                } else {
                    hintList.open(response);
                }
            } else { // response is a deferred
                deferredHints = response;
                response.done(function (hints) {
                    // Guard against timing issues where the session ends before the
                    // response gets a chance to execute the callback.  If the session
                    // ends first while still waiting on the response, then hintList
                    // will get cleared up.
                    if (!hintList) {
                        return;
                    }

                    if (hintList.isOpen()) {
                        // the session is open
                        hintList.update(hints);
                    } else {
                        hintList.open(hints);
                    }
                });
            }
        }
    }

Public API

hasValidExclusion

Test whether the provider has an exclusion that is still the same as text after the cursor.

exclusion
string

Text not to be overwritten when the provider inserts the selected hint.

textAfterCursor
string

Text that is immediately after the cursor position.

Returns: boolean

true if the exclusion is not null and is exactly the same as textAfterCursor, false otherwise.

    function hasValidExclusion(exclusion, textAfterCursor) {
        return (exclusion && exclusion === textAfterCursor);
    }

Public API

isOpen

Test if a hint popup is open.

Returns: boolean

— true if the hints are open, false otherwise.

    function isOpen() {
        return (hintList && hintList.isOpen());
    }

Public API

registerHintProvider

The method by which a CodeHintProvider registers its willingness to
providing hints for editors in a given language.

provider
non-nullable
CodeHintProvider

The hint provider to be registered, described below.

languageIds
non-nullable
Array.<string>

The set of language ids for which the provider is capable of providing hints. If the special language id name «all» is included then the provider may be called for any language.

priority
nullable
number

Used to break ties among hint providers for a particular language. Providers with a higher number will be asked for hints before those with a lower priority value. Defaults to zero.

    function registerHintProvider(providerInfo, languageIds, priority) {
        var providerObj = { provider: providerInfo,
                            priority: priority || 0 };

        if (languageIds.indexOf("all") !== -1) {
            // Ignore anything else in languageIds and just register for every language. This includes
            // the special "all" language since its key is in the hintProviders map from the beginning.
            var languageId;
            for (languageId in hintProviders) {
                if (hintProviders.hasOwnProperty(languageId)) {
                    hintProviders[languageId].push(providerObj);
                    hintProviders[languageId].sort(_providerSort);
                }
            }
        } else {
            languageIds.forEach(function (languageId) {
                if (!hintProviders[languageId]) {
                    // Initialize provider list with any existing all-language providers
                    hintProviders[languageId] = Array.prototype.concat(hintProviders.all);
                }
                hintProviders[languageId].push(providerObj);
                hintProviders[languageId].sort(_providerSort);
            });
        }
    }