LanguageManager.js

/*
 * GNU AGPL-3.0 License
 *
 * Copyright (c) 2021 - present core.ai . All rights reserved.
 * Original work Copyright (c) 2012 - 2021 Adobe Systems Incorporated. All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
 *
 */


// @INCLUDE_IN_API_DOCS


/*unittests: LanguageManager*/

/**
 * LanguageManager provides access to the languages supported by Brackets
 *
 * To find out which languages we support by default, have a look at languages.json.
 *
 * To get access to an existing language, call getLanguage():
 *
 *     var language = LanguageManager.getLanguage("<id>");
 *
 * To define your own languages, call defineLanguage():
 *
 *     LanguageManager.defineLanguage("haskell", {
 *         name: "Haskell",
 *         mode: "haskell",
 *         fileExtensions: ["hs"],
 *         blockComment: ["{-", "-}"],
 *         lineComment: ["--"]
 *     });
 *
 * To use that language and its related mode, wait for the returned promise to be resolved:
 *
 *     LanguageManager.defineLanguage("haskell", definition).done(function (language) {
 *         console.log("Language " + language.getName() + " is now available!");
 *     });
 *
 * The extension can also contain dots:
 *
 *     LanguageManager.defineLanguage("literatecoffeescript", {
 *         name: "Literate CoffeeScript",
 *         mode: "coffeescript",
 *         fileExtensions: ["litcoffee", "coffee.md"]
 *     });
 *
 * You can also specify file names:
 *
 *     LanguageManager.defineLanguage("makefile", {
 *         name: "Make",
 *         mode: ["null", "text/plain"],
 *         fileNames: ["Makefile"]
 *     });
 *
 * You can combine file names and extensions, or not define them at all.
 *
 * You can also refine an existing language:
 *
 *     var language = LanguageManager.getLanguage("haskell");
 *     language.setLineCommentSyntax(["--"]);
 *     language.setBlockCommentSyntax("{-", "-}");
 *     language.addFileExtension("lhs");
 *
 * Some CodeMirror modes define variations of themselves. They are called MIME modes.
 * To find existing MIME modes, search for "CodeMirror.defineMIME" in thirdparty/CodeMirror/mode
 * For instance, C++, C# and Java all use the clike (C-like) mode with different settings and a different MIME name.
 * You can refine the mode definition by specifying the MIME mode as well:
 *
 *     LanguageManager.defineLanguage("csharp", {
 *         name: "C#",
 *         mode: ["clike", "text/x-csharp"],
 *         ...
 *     });
 *
 * Defining the base mode is still necessary to know which file to load.
 * However, language.getMode() will return just the MIME mode if one was
 * specified.
 *
 * If you need to configure a mode, you can just create a new MIME mode and use that:
 *
 *     CodeMirror.defineMIME("text/x-brackets-html", {
 *         "name": "htmlmixed",
 *         "scriptTypes": [{"matches": /\/x-handlebars-template|\/x-mustache/i,
 *                        "mode": null}]
 *     });
 *
 *     LanguageManager.defineLanguage("html", {
 *         name: "HTML",
 *         mode: ["htmlmixed", "text/x-brackets-html"],
 *         ...
 *     });
 *
 * If a mode is not shipped with our CodeMirror distribution, you need to first load it yourself.
 * If the mode is part of our CodeMirror distribution, it gets loaded automatically.
 *
 * You can also defines binary file types, i.e. Brackets supports image files by default,
 * such as *.jpg, *.png etc.
 * Binary files do not require mode because modes are specific to CodeMirror, which
 * only handles text based file types.
 * To register a binary language the isBinary flag must be set, i.e.
 *
 *     LanguageManager.defineLanguage("audio", {
 *         name: "Audio",
 *         fileExtensions: ["mp3", "wav", "aif", "aiff", "ogg"],
 *         isBinary: true
 *     });
 *
 *
 * LanguageManager dispatches two events:
 *
 *  - languageAdded -- When any new Language is added. 2nd arg is the new Language.
 *  - languageModified -- When the attributes of a Language change, or when the Language gains or loses
 *          file extension / filename mappings. 2nd arg is the modified Language.
 */
define(function (require, exports, module) {



    // Dependencies
    var CodeMirror            = require("thirdparty/CodeMirror/lib/codemirror"),
        EventDispatcher       = require("utils/EventDispatcher"),
        Async                 = require("utils/Async"),
        FileUtils             = require("file/FileUtils"),
        Strings               = require("strings"),
        _defaultLanguagesJSON = require("text!language/languages.json"),
        _                     = require("thirdparty/lodash"),

        // PreferencesManager is loaded near the end of the file
        PreferencesManager;

    // State
    var _fallbackLanguage               = null,
        _pendingLanguages               = {},
        _languages                      = {},
        _baseFileExtensionToLanguageMap = {},
        _fileExtensionToLanguageMap     = Object.create(_baseFileExtensionToLanguageMap),
        _fileNameToLanguageMap          = {},
        _filePathToLanguageMap          = {},
        _modeToLanguageMap              = {},
        _ready;

    // Constants

    var _EXTENSION_MAP_PREF = "language.fileExtensions",
        _NAME_MAP_PREF      = "language.fileNames";

    // Tracking for changes to mappings made by preferences
    var _prefState = {};

    _prefState[_EXTENSION_MAP_PREF] = {
        last: {},
        overridden: {},
        add: "addFileExtension",
        remove: "removeFileExtension",
        get: "getLanguageForExtension"
    };

    _prefState[_NAME_MAP_PREF] = {
        last: {},
        overridden: {},
        add: "addFileName",
        remove: "removeFileName",
        get: "getLanguageForPath"
    };

    // Helper functions

    /**
     * Checks whether value is a non-empty string. Reports an error otherwise.
     * If no deferred is passed, console.error is called.
     * Otherwise the deferred is rejected with the error message.
     * @private
     * @param {*}                value         The value to validate
     * @param {!string}          description   A helpful identifier for value
     * @param {?jQuery.Deferred} deferred      A deferred to reject with the error message in case of an error
     * @return {boolean} True if the value is a non-empty string, false otherwise
     */
    function _validateNonEmptyString(value, description, deferred) {
        var reportError = deferred ? deferred.reject : console.error;

        // http://stackoverflow.com/questions/1303646/check-whether-variable-is-number-or-string-in-javascript
        if (Object.prototype.toString.call(value) !== "[object String]") {
            reportError(description + " must be a string");
            return false;
        }
        if (value === "") {
            reportError(description + " must not be empty");
            return false;
        }
        return true;
    }

    /**
     * Monkey-patch CodeMirror to prevent modes from being overwritten by extensions.
     * We may rely on the tokens provided by some of these modes.
     * @private
     */
    function _patchCodeMirror() {
        var _original_CodeMirror_defineMode = CodeMirror.defineMode;
        function _wrapped_CodeMirror_defineMode(name) {
            if (CodeMirror.modes[name]) {
                console.error("There already is a CodeMirror mode with the name \"" + name + "\"");
                return;
            }
            _original_CodeMirror_defineMode.apply(CodeMirror, arguments);
        }
        CodeMirror.defineMode = _wrapped_CodeMirror_defineMode;
    }

    /**
     * Adds a global mode-to-language association.
     * @private
     * @param {!string} mode The mode to associate the language with
     * @param {!Language} language The language to associate with the mode
     */
    function _setLanguageForMode(mode, language) {
        if (_modeToLanguageMap[mode]) {
            console.warn("CodeMirror mode \"" + mode + "\" is already used by language " + _modeToLanguageMap[mode]._name + " - cannot fully register language " + language._name +
                         " using the same mode. Some features will treat all content with this mode as language " + _modeToLanguageMap[mode]._name);
            return;
        }

        _modeToLanguageMap[mode] = language;
    }

    /**
     * Resolves a language ID to a Language object.
     * File names have a higher priority than file extensions.
     * @param {!string} id Identifier for this language: lowercase letters, digits, and _ separators (e.g. "cpp", "foo_bar", "c99")
     * @return {Language} The language with the provided identifier or undefined
     */
    function getLanguage(id) {
        return _languages[id];
    }

    /**
     * Resolves a file extension to a Language object.
     * *Warning:* it is almost always better to use getLanguageForPath(), since Language can depend
     * on file name and even full path. Use this API only if no relevant file/path exists.
     * @param {!string} extension Extension that language should be resolved for
     * @return {?Language} The language for the provided extension or null if none exists
     */
    function getLanguageForExtension(extension) {
        return _fileExtensionToLanguageMap[extension.toLowerCase()];
    }

    /**
     * Resolves a file path to a Language object.
     * @param {string} path Path to the file to find a language for
     * @param {boolean} [ignoreOverride] If set to true will cause the lookup to ignore any
     *      overrides and return default binding. By default override is not ignored.
     *
     * @return {Language} The language for the provided file type or the fallback language
     */
    function getLanguageForPath(path, ignoreOverride) {
        var fileName,
            language = _filePathToLanguageMap[path],
            extension,
            parts;

        // if there's an override, return it
        if (!ignoreOverride && language) {
            return language;
        }

        fileName = FileUtils.getBaseName(path).toLowerCase();
        language = _fileNameToLanguageMap[fileName];

        // If no language was found for the file name, use the file extension instead
        if (!language) {
            // Split the file name into parts:
            //   "foo.coffee.md"   => ["foo", "coffee", "md"]
            //   ".profile.bak"    => ["", "profile", "bak"]
            //   "1. Vacation.txt" => ["1", " Vacation", "txt"]
            parts = fileName.split(".");

            // A leading dot does not indicate a file extension, but marks the file as hidden => remove it
            if (parts[0] === "") {
                // ["", "profile", "bak"] => ["profile", "bak"]
                parts.shift();
            }

            // The first part is assumed to be the title, not the extension => remove it
            //   ["foo", "coffee", "md"]   => ["coffee", "md"]
            //   ["profile", "bak"]        => ["bak"]
            //   ["1", " Vacation", "txt"] => [" Vacation", "txt"]
            parts.shift();

            // Join the remaining parts into a file extension until none are left or a language was found
            while (!language && parts.length) {
                // First iteration:
                //   ["coffee", "md"]     => "coffee.md"
                //   ["bak"]              => "bak"
                //   [" Vacation", "txt"] => " Vacation.txt"
                // Second iteration (assuming no language was found for "coffee.md"):
                //   ["md"]  => "md"
                //   ["txt"] => "txt"
                extension = parts.join(".");
                language  = _fileExtensionToLanguageMap[extension];
                // Remove the first part
                // First iteration:
                //   ["coffee", "md"]     => ["md"]
                //   ["bak"]              => []
                //   [" Vacation", "txt"] => ["txt"]
                // Second iteration:
                //   ["md"]  => []
                //   ["txt"] => []
                parts.shift();
            }
        }

        return language || _fallbackLanguage;
    }

    /**
     * Returns a map of all the languages currently defined in the LanguageManager. The key to
     * the map is the language id and the value is the language object.
     *
     * @return {Object.<string, Language>} A map containing all of the
     *      languages currently defined.
     */
    function getLanguages() {
        return $.extend({}, _languages); // copy to prevent modification
    }

    /**
     * Resolves a CodeMirror mode to a Language object.
     * @private
     * @param {!string} mode CodeMirror mode
     * @return {Language} The language for the provided mode or the fallback language
     */
    function _getLanguageForMode(mode) {
        var language = _modeToLanguageMap[mode];
        if (language) {
            return language;
        }

        // In case of unsupported languages
        console.log("Called LanguageManager._getLanguageForMode with a mode for which no language has been registered:", mode);
        return _fallbackLanguage;
    }

    /**
     * @private
     * Notify listeners when a language is added
     * @param {!Language} language The new language
     */
    function _triggerLanguageAdded(language) {
        // finally, store language to _language map
        _languages[language.getId()] = language;
        exports.trigger("languageAdded", language);
    }

    /**
     * @private
     * Notify listeners when a language is modified
     * @param {!Language} language The modified language
     */
    function _triggerLanguageModified(language) {
        exports.trigger("languageModified", language);
    }

    /**
     * Adds a language mapping for the specified fullPath. If language is falsy (null or undefined), the mapping
     * is removed. The override is NOT persisted across Brackets sessions.
     *
     * @param {!fullPath} fullPath absolute path of the file
     * @param {?object} language language to associate the file with or falsy value to remove any existing override
     */
    function setLanguageOverrideForPath(fullPath, language) {
        var oldLang = getLanguageForPath(fullPath);
        if (!language) {
            delete _filePathToLanguageMap[fullPath];
        } else {
            _filePathToLanguageMap[fullPath] = language;
        }
        var newLang = getLanguageForPath(fullPath);

        // Old language changed since this path is no longer mapped to it
        _triggerLanguageModified(oldLang);
        // New language changed since a path is now mapped to it that wasn't before
        _triggerLanguageModified(newLang);
    }

    /**
     * Resets all the language overrides for file paths. Used by unit tests only.
     * @private
     */
    function _resetPathLanguageOverrides() {
        _filePathToLanguageMap = {};
    }

    /**
     * Get the file extension (excluding ".") given a path OR a bare filename.
     * Returns "" for names with no extension.
     * If the only `.` in the file is the first character,
     * returns "" as this is not considered an extension.
     * This method considers known extensions which include `.` in them.
     *
     * @param {string} fullPath full path to a file or directory
     * @return {string} Returns the extension of a filename or empty string if
     * the argument is a directory or a filename with no extension
     */
    function getCompoundFileExtension(fullPath) {
        var baseName = FileUtils.getBaseName(fullPath),
            parts = baseName.split(".");

        // get rid of file name
        parts.shift();
        if (baseName[0] === ".") {
            // if starts with a `.`, then still consider it as file name
            parts.shift();
        }

        var extension = [parts.pop()], // last part is always an extension
            i = parts.length;
        while (i--) {
            if (getLanguageForExtension(parts[i])) {
                extension.unshift(parts[i]);
            } else {
                break;
            }
        }
        return extension.join(".");
    }



    /**
     * Model for a language.
     * @constructor
     */
    function Language() {
        this._fileExtensions    = [];
        this._fileNames         = [];
        this._modeToLanguageMap = {};
        this._lineCommentSyntax = [];
    }


    /**
     * Identifier for this language
     * @private
     * @type {string}
     */
    Language.prototype._id = null;

    /**
     * Human-readable name of this language
     * @private
     * @type {string}
     */
    Language.prototype._name = null;

    /**
     * CodeMirror mode for this language
     * @private
     * @type {string}
     */
    Language.prototype._mode = null;

    /**
     * File extensions that use this language
     * @private
     * @type {Array.<string>}
     */
    Language.prototype._fileExtensions = null;

    /**
     * File names for extensionless files that use this language
     * @private
     * @type {Array.<string>}
     */
    Language.prototype._fileNames = null;

    /**
     * Line comment syntax
     * @private
     * @type {Array.<string>}
     */
    Language.prototype._lineCommentSyntax = null;

    /**
     * Which language to use for what CodeMirror mode
     * @private
     * @type {Object.<string,Language>}
     */
    Language.prototype._modeToLanguageMap = null;

    /**
     * Block comment syntax
     * @private
     * @type {{ prefix: string, suffix: string }}
     */
    Language.prototype._blockCommentSyntax = null;

    /**
     * Whether or not the language is binary
     * @private
     * @type {boolean}
     */
    Language.prototype._isBinary = false;

    /**
     * Returns the identifier for this language.
     * @return {string} The identifier
     */
    Language.prototype.getId = function () {
        return this._id;
    };

    /**
     * Sets the identifier for this language or prints an error to the console.
     * @private
     * @param {!string} id Identifier for this language: lowercase letters, digits, and _ separators (e.g. "cpp", "foo_bar", "c99")
     * @return {boolean} Whether the ID was valid and set or not
     */
    Language.prototype._setId = function (id) {
        if (!_validateNonEmptyString(id, "Language ID")) {
            return false;
        }
        // Make sure the ID is a string that can safely be used universally by the computer - as a file name, as an object key, as part of a URL, etc.
        // Hence we use "_" instead of "." since the latter often has special meaning
        if (!id.match(/^[a-z0-9]+(_[a-z0-9]+)*$/)) {
            console.error("Invalid language ID \"" + id + "\": Only groups of lower case letters and numbers are allowed, separated by underscores.");
            return false;
        }

        this._id = id;
        return true;
    };

    /**
     * Returns the human-readable name of this language.
     * @return {string} The name
     */
    Language.prototype.getName = function () {
        return this._name;
    };

    /**
     * Sets the human-readable name of this language or prints an error to the console.
     * @private
     * @param {!string} name Human-readable name of the language, as it's commonly referred to (e.g. "C++")
     * @return {boolean} Whether the name was valid and set or not
     */
    Language.prototype._setName = function (name) {
        if (!_validateNonEmptyString(name, "name")) {
            return false;
        }

        this._name = name;
        return true;
    };

    /**
     * Returns the CodeMirror mode for this language.
     * @return {string} The mode
     */
    Language.prototype.getMode = function () {
        return this._mode;
    };

    /**
     * Loads a mode and sets it for this language.
     * @private
     * @param {(string|Array.<string>)} mode  CodeMirror mode (e.g. "htmlmixed"), optionally paired with a MIME mode defined by
     *      that mode (e.g. ["clike", "text/x-c++src"]). Unless the mode is located in thirdparty/CodeMirror/mode/"name"/"name".js,
     *      you need to first load it yourself.
     * @return {$.Promise} A promise object that will be resolved when the mode is loaded and set
     */
    Language.prototype._loadAndSetMode = function (mode) {
        var result      = new $.Deferred(),
            self        = this,
            mimeMode; // Mode can be an array specifying a mode plus a MIME mode defined by that mode ["clike", "text/x-c++src"]

        if (Array.isArray(mode)) {
            if (mode.length !== 2) {
                result.reject("Mode must either be a string or an array containing two strings");
                return result.promise();
            }
            mimeMode = mode[1];
            mode = mode[0];
        }

        // mode must not be empty. Use "null" (the string "null") mode for plain text
        if (!_validateNonEmptyString(mode, "mode", result)) {
            result.reject();
            return result.promise();
        }

        var finish = function () {
            if (!CodeMirror.modes[mode]) {
                result.reject("CodeMirror mode \"" + mode + "\" is not loaded");
                return;
            }

            if (mimeMode) {
                var modeConfig = CodeMirror.mimeModes[mimeMode];

                if (!modeConfig) {
                    result.reject("CodeMirror MIME mode \"" + mimeMode + "\" not found");
                    return;
                }
            }

            // This mode is now only about what to tell CodeMirror
            // The base mode was only necessary to load the proper mode file
            self._mode = mimeMode || mode;
            self._wasModified();

            result.resolve(self);
        };

        if (CodeMirror.modes[mode]) {
            finish();
        } else {
            require(["thirdparty/CodeMirror/mode/" + mode + "/" + mode], finish);
        }

        return result.promise();
    };

    /**
     * Returns an array of file extensions for this language.
     * @return {Array.<string>} File extensions used by this language
     */
    Language.prototype.getFileExtensions = function () {
        // Use concat to create a copy of this array, preventing external modification
        return this._fileExtensions.concat();
    };

    /**
     * Returns an array of file names for extensionless files that use this language.
     * @return {Array.<string>} Extensionless file names used by this language
     */
    Language.prototype.getFileNames = function () {
        // Use concat to create a copy of this array, preventing external modification
        return this._fileNames.concat();
    };

    /**
     * Adds one or more file extensions to this language.
     * @param {!string|Array.<string>} extension A file extension (or array thereof) used by this language
     */
    Language.prototype.addFileExtension = function (extension) {
        if (Array.isArray(extension)) {
            extension.forEach(this._addFileExtension.bind(this));
        } else {
            this._addFileExtension(extension);
        }
    };
    Language.prototype._addFileExtension = function (extension) {
        // Remove a leading dot if present
        if (extension.charAt(0) === ".") {
            extension = extension.substr(1);
        }

        // Make checks below case-INsensitive
        extension = extension.toLowerCase();

        if (this._fileExtensions.indexOf(extension) === -1) {
            this._fileExtensions.push(extension);

            var language = _fileExtensionToLanguageMap[extension];
            if (language) {
                console.warn("Cannot register file extension \"" + extension + "\" for " + this._name + ", it already belongs to " + language._name);
            } else {
                _fileExtensionToLanguageMap[extension] = this;
            }

            this._wasModified();
        } else if(!_fileExtensionToLanguageMap[extension]) {

            // Language should be in the extension map but isn't
            _fileExtensionToLanguageMap[extension] = this;
            this._wasModified();
        }
    };

    /**
     * Unregisters one or more file extensions from this language.
     * @param {!string|Array.<string>} extension File extension (or array thereof) to stop using for this language
     */
    Language.prototype.removeFileExtension = function (extension) {
        if (Array.isArray(extension)) {
            extension.forEach(this._removeFileExtension.bind(this));
        } else {
            this._removeFileExtension(extension);
        }
    };
    Language.prototype._removeFileExtension = function (extension) {
        // Remove a leading dot if present
        if (extension.charAt(0) === ".") {
            extension = extension.substr(1);
        }

        // Make checks below case-INsensitive
        extension = extension.toLowerCase();

        var index = this._fileExtensions.indexOf(extension);
        if (index !== -1) {
            this._fileExtensions.splice(index, 1);

            delete _fileExtensionToLanguageMap[extension];

            this._wasModified();
        }
    };

    /**
     * Adds one or more file names to the language which is used to match files that don't have extensions like "Makefile" for example.
     * @param {!string|Array.<string>} extension An extensionless file name (or array thereof) used by this language
     */
    Language.prototype.addFileName = function (name) {
        if (Array.isArray(name)) {
            name.forEach(this._addFileName.bind(this));
        } else {
            this._addFileName(name);
        }
    };
    Language.prototype._addFileName = function (name) {
        // Make checks below case-INsensitive
        name = name.toLowerCase();

        if (this._fileNames.indexOf(name) === -1) {
            this._fileNames.push(name);

            var language = _fileNameToLanguageMap[name];
            if (language) {
                console.warn("Cannot register file name \"" + name + "\" for " + this._name + ", it already belongs to " + language._name);
            } else {
                _fileNameToLanguageMap[name] = this;
            }

            this._wasModified();
        }
    };

    /**
     * Unregisters one or more file names from this language.
     * @param {!string|Array.<string>} extension An extensionless file name (or array thereof) used by this language
     */
    Language.prototype.removeFileName = function (name) {
        if (Array.isArray(name)) {
            name.forEach(this._removeFileName.bind(this));
        } else {
            this._removeFileName(name);
        }
    };
    Language.prototype._removeFileName = function (name) {
        // Make checks below case-INsensitive
        name = name.toLowerCase();

        var index = this._fileNames.indexOf(name);
        if (index !== -1) {
            this._fileNames.splice(index, 1);

            delete _fileNameToLanguageMap[name];

            this._wasModified();
        }
    };

    /**
     * Returns whether the line comment syntax is defined for this language.
     * @return {boolean} Whether line comments are supported
     */
    Language.prototype.hasLineCommentSyntax = function () {
        return this._lineCommentSyntax.length > 0;
    };

    /**
     * Returns an array of prefixes to use for line comments.
     * @return {Array.<string>} The prefixes
     */
    Language.prototype.getLineCommentPrefixes = function () {
        return this._lineCommentSyntax;
    };

    /**
     * Sets the prefixes to use for line comments in this language or prints an error to the console.
     * @param {!(string|Array.<string>)} prefix Prefix string or an array of prefix strings
     *   to use for line comments (e.g. "//" or ["//", "#"])
     * @return {boolean} Whether the syntax was valid and set or not
     */
    Language.prototype.setLineCommentSyntax = function (prefix) {
        var prefixes = Array.isArray(prefix) ? prefix : [prefix];
        var i;

        if (prefixes.length) {
            this._lineCommentSyntax = [];
            for (i = 0; i < prefixes.length; i++) {
                _validateNonEmptyString(String(prefixes[i]), Array.isArray(prefix) ? "prefix[" + i + "]" : "prefix");

                this._lineCommentSyntax.push(prefixes[i]);
            }
            this._wasModified();
        } else {
            console.error("The prefix array should not be empty");
        }

        return true;
    };

    /**
     * Returns whether the block comment syntax is defined for this language.
     * @return {boolean} Whether block comments are supported
     */
    Language.prototype.hasBlockCommentSyntax = function () {
        return Boolean(this._blockCommentSyntax);
    };

    /**
     * Returns the prefix to use for block comments.
     * @return {string} The prefix
     */
    Language.prototype.getBlockCommentPrefix = function () {
        return this._blockCommentSyntax && this._blockCommentSyntax.prefix;
    };

    /**
     * Returns the suffix to use for block comments.
     * @return {string} The suffix
     */
    Language.prototype.getBlockCommentSuffix = function () {
        return this._blockCommentSyntax && this._blockCommentSyntax.suffix;
    };

    /**
     * Sets the prefix and suffix to use for blocks comments in this language or prints an error to the console.
     * @param {!string} prefix Prefix string to use for block comments (e.g. "< !--")
     * @param {!string} suffix Suffix string to use for block comments (e.g. "-->")
     * @return {boolean} Whether the syntax was valid and set or not
     */
    Language.prototype.setBlockCommentSyntax = function (prefix, suffix) {
        if (!_validateNonEmptyString(prefix, "prefix") || !_validateNonEmptyString(suffix, "suffix")) {
            return false;
        }

        this._blockCommentSyntax = { prefix: prefix, suffix: suffix };
        this._wasModified();

        return true;
    };

    /**
     * Returns either a language associated with the mode or the fallback language.
     * Used to disambiguate modes used by multiple languages.
     * @param {!string} mode The mode to associate the language with
     * @return {Language} This language if it uses the mode, or whatever {@link #_getLanguageForMode} returns
     */
    Language.prototype.getLanguageForMode = function (mode) {
        if (mode === this._mode) {
            return this;
        }
        return this._modeToLanguageMap[mode] || _getLanguageForMode(mode);
    };

    /**
     * Overrides a mode-to-language association for this particular language only or prints an error to the console.
     * Used to disambiguate modes used by multiple languages.
     * @private
     * @param {!string} mode The mode to associate the language with
     * @param {!Language} language The language to associate with the mode
     * @return {boolean} Whether the mode-to-language association was valid and set or not
     * @private
     */
    Language.prototype._setLanguageForMode = function (mode, language) {
        if (mode === this._mode && language !== this) {
            console.error("A language must always map its mode to itself");
            return false;
        }

        this._modeToLanguageMap[mode] = language;
        this._wasModified();

        return true;
    };

    /**
     * Determines whether this is the fallback language or not
     * @return {boolean} True if this is the fallback language, false otherwise
     */
    Language.prototype.isFallbackLanguage = function () {
        return this === _fallbackLanguage;
    };

    /**
     * Trigger the "languageModified" event if this language is registered already
     * @private
     * @see #_triggerLanguageModified
     */
    Language.prototype._wasModified = function () {
        if (_languages[this._id]) {
            _triggerLanguageModified(this);
        }
    };

    /**
     * Indicates whether or not the language is binary (e.g., image or audio).
     * @return {boolean}
     */
    Language.prototype.isBinary = function () {
        return this._isBinary;
    };

    /**
     * Sets whether or not the language is binary
     * @private
     * @param {!boolean} isBinary
     */
    Language.prototype._setBinary = function (isBinary) {
        this._isBinary = isBinary;
    };

    /**
     * Defines a language.
     *
     * @param {!string}               id                        Unique identifier for this language: lowercase letters, digits, and _ separators (e.g. "cpp", "foo_bar", "c99")
     * @param {!Object}               definition                An object describing the language
     * @param {!string}               definition.name           Human-readable name of the language, as it's commonly referred to (e.g. "C++")
     * @param {Array.<string>}        definition.fileExtensions List of file extensions used by this language (e.g. ["php", "php3"] or ["coffee.md"] - may contain dots)
     * @param {Array.<string>}        definition.fileNames      List of exact file names (e.g. ["Makefile"] or ["package.json]). Higher precedence than file extension.
     * @param {Array.<string>}        definition.blockComment   Array with two entries defining the block comment prefix and suffix (e.g. ["< !--", "-->"])
     * @param {(string|Array.<string>)} definition.lineComment  Line comment prefixes (e.g. "//" or ["//", "#"])
     * @param {(string|Array.<string>)} definition.mode         CodeMirror mode (e.g. "htmlmixed"), optionally with a MIME mode defined by that mode ["clike", "text/x-c++src"]
     *                                                          Unless the mode is located in thirdparty/CodeMirror/mode/"name"/"name".js, you need to first load it yourself.
     *
     * @return {$.Promise} A promise object that will be resolved with a Language object
     **/
    function defineLanguage(id, definition) {
        var result = new $.Deferred();

        if (_pendingLanguages[id]) {
            result.reject("Language \"" + id + "\" is waiting to be resolved.");
            return result.promise();
        }
        if (_languages[id]) {
            result.reject("Language \"" + id + "\" is already defined");
            return result.promise();
        }

        var language       = new Language(),
            name           = definition.name,
            fileExtensions = definition.fileExtensions,
            fileNames      = definition.fileNames,
            blockComment   = definition.blockComment,
            lineComment    = definition.lineComment,
            i,
            l;

        function _finishRegisteringLanguage() {
            if (fileExtensions) {
                for (i = 0, l = fileExtensions.length; i < l; i++) {
                    language.addFileExtension(fileExtensions[i]);
                }
            }
            // register language file names after mode has loaded
            if (fileNames) {
                for (i = 0, l = fileNames.length; i < l; i++) {
                    language.addFileName(fileNames[i]);
                }
            }

            language._setBinary(!!definition.isBinary);

            // store language to language map
            _languages[language.getId()] = language;

            // restore any preferences for non-default languages
            if(PreferencesManager) {
                _updateFromPrefs(_EXTENSION_MAP_PREF);
                _updateFromPrefs(_NAME_MAP_PREF);
            }
        }

        if (!language._setId(id) || !language._setName(name) ||
                (blockComment && !language.setBlockCommentSyntax(blockComment[0], blockComment[1])) ||
                (lineComment && !language.setLineCommentSyntax(lineComment))) {
            result.reject();
            return result.promise();
        }


        if (definition.isBinary) {