kopia lustrzana https://github.com/c9/core
1019 wiersze
45 KiB
JavaScript
1019 wiersze
45 KiB
JavaScript
/*
|
|
* Cloud9 Language Foundation
|
|
*
|
|
* @copyright 2013, Ajax.org B.V.
|
|
*/
|
|
|
|
/**
|
|
* This module is used as a base class for language handlers.
|
|
* It provides properties, helper functions, and functions that
|
|
* can be overridden by language handlers to implement
|
|
* language services such as code completion.
|
|
*
|
|
* @class language.base_handler
|
|
*/
|
|
define(function(require, exports, module) {
|
|
|
|
module.exports = {
|
|
|
|
/**
|
|
* Indicates the handler handles editors, the immediate window,
|
|
* and anything else.
|
|
*/
|
|
HANDLES_ANY: 0,
|
|
|
|
/**
|
|
* Indicates the handler only handles editors, not the immediate window.
|
|
*/
|
|
HANDLES_EDITOR: 1,
|
|
|
|
/**
|
|
* Indicates the handler only handles the immediate window, not editors.
|
|
*/
|
|
HANDLES_IMMEDIATE: 2,
|
|
|
|
/**
|
|
* Indicates the handler only handles the immediate window, not editors.
|
|
*/
|
|
HANDLES_EDITOR_AND_IMMEDIATE: 3,
|
|
|
|
/**
|
|
* The language this worker is currently operating on.
|
|
* @type {String}
|
|
*/
|
|
language: null,
|
|
|
|
/**
|
|
* The path of the file this worker is currently operating on.
|
|
* @type {String}
|
|
*/
|
|
path: null,
|
|
|
|
/**
|
|
* The current workspace directory.
|
|
* @type {String}
|
|
*/
|
|
workspaceDir: null,
|
|
|
|
/**
|
|
* The current document this worker is operating on.
|
|
*
|
|
* @type {Document}
|
|
*/
|
|
doc: null,
|
|
|
|
/**
|
|
* Indicates this completer cannot complete zero-length identifiers.
|
|
* @internal
|
|
*/
|
|
$disableZeroLengthCompletion: false,
|
|
|
|
/**
|
|
* An identifier length at which completions should be recomputed.
|
|
* @internal
|
|
*/
|
|
$recacheCompletionLength: null,
|
|
|
|
// UTILITIES
|
|
|
|
/**
|
|
* Utility function, used to determine whether a certain feature is enabled
|
|
* in the user's preferences.
|
|
*
|
|
* Should not be overridden by inheritors.
|
|
*
|
|
* @deprecated Use worker_util#isFeatureEnabled instead
|
|
*
|
|
* @param {String} name The name of the feature, e.g. "unusedFunctionArgs"
|
|
* @return {Boolean}
|
|
*/
|
|
isFeatureEnabled: function(name) {
|
|
/*global disabledFeatures*/
|
|
return !disabledFeatures[name];
|
|
},
|
|
|
|
/**
|
|
* Utility function, used to determine the identifier regex for the
|
|
* current language, by invoking {@link #getIdentifierRegex} on its handlers.
|
|
*
|
|
* Should not be overridden by inheritors.
|
|
*
|
|
* @deprecated Use worker_util#getIdentifierRegex instead
|
|
*
|
|
* @return {RegExp}
|
|
*/
|
|
$getIdentifierRegex: function() {
|
|
return null;
|
|
},
|
|
|
|
/**
|
|
* Get an event emitter for emitting and receiving
|
|
* UI events.
|
|
*
|
|
* Example:
|
|
*
|
|
* ```
|
|
* worker_util.getEmitter().emit("log", "Hello there")
|
|
* ```
|
|
*
|
|
* which can be received by a UI plugin using:
|
|
*
|
|
* ```
|
|
* language.registerLanguageHandler("myplugin", function(err, handler) {
|
|
* if (err) return console.error(err);
|
|
*
|
|
* handler.on("log", function(e) {
|
|
* console.log(e);
|
|
* });
|
|
* });
|
|
* ```
|
|
*
|
|
* @param {String} [overridePath] An optional path of the plugin for which to send/receive UI events,
|
|
* e.g. "c9.ide.language.python/worker/python_completer" to send/receive
|
|
* events in name of the Python completer plugin.
|
|
*/
|
|
getEmitter: function(overridePath) {
|
|
// implemented by worker
|
|
throw new Error("getEmitter() is not available yet, please call after init()");
|
|
},
|
|
|
|
// OVERRIDABLE ACCESORS
|
|
|
|
/**
|
|
* Returns whether this language handler should be enabled for the given
|
|
* file.
|
|
*
|
|
* MUST be overridden by inheritors.
|
|
*
|
|
* @param {String} language to check the handler against
|
|
* @return {Boolean}
|
|
*/
|
|
handlesLanguage: function(language) {
|
|
throw new Error("base_handler.handlesLanguage() is not overridden");
|
|
},
|
|
|
|
/**
|
|
* Returns whether this language handler should be used in a
|
|
* particular kind of editor.
|
|
*
|
|
* MAY be overridden by inheritors; returns {@link #HANDLES_EDITOR}
|
|
* by default.
|
|
*
|
|
* @return {Number} One of {@link #HANDLES_EDITOR},
|
|
* {@link #HANDLES_IMMEDIATE}, or
|
|
* {@link #HANDLES_EDITOR_AND_IMMEDIATE}, or
|
|
* {@link #HANDLES_ANY}.
|
|
*/
|
|
handlesEditor: function() {
|
|
return this.HANDLES_EDITOR;
|
|
},
|
|
|
|
/**
|
|
* Returns the maximum file size this language handler supports.
|
|
* Should return Infinity if size does not matter.
|
|
* Default is 10.000 lines of 80 characters.
|
|
*
|
|
* MAY be overridden by inheritors.
|
|
*
|
|
* @return {Number}
|
|
*/
|
|
getMaxFileSizeSupported: function() {
|
|
// Moderately conservative default (well, still 800K)
|
|
return 10 * 1000 * 80;
|
|
},
|
|
|
|
/**
|
|
* Returns a regular expression for identifiers in the handler's language.
|
|
* If not specified, /[A-Za-z0-9$_]/ is used.
|
|
*
|
|
* Note: to indicate dollars are allowed at the start of identifiers
|
|
* (like with php $variables), include '$$'' in the regex, e.g.
|
|
* /[A-Z0-9$$_]/.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement code completion.
|
|
*
|
|
* @return RegExp
|
|
*/
|
|
getIdentifierRegex: function() {
|
|
return null;
|
|
},
|
|
|
|
/**
|
|
* Returns a regular expression used to trigger code completion.
|
|
* If a non-null value is returned, it is assumed continous completion
|
|
* is supported for this language.
|
|
*
|
|
* This regex may match the last character, e.g. for Java-like O.O. languages
|
|
* you might might want to use: /^\.$/
|
|
*
|
|
* The regex may also match the whole preceding line, e.g.
|
|
* /console\.$/. Only when the regex ends with a $ will it be tried
|
|
* as a regex that matches against the whole line.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement code completion.
|
|
* Default implementation returns null.
|
|
*
|
|
* @return RegExp
|
|
*/
|
|
getCompletionRegex: function() {
|
|
return null;
|
|
},
|
|
|
|
/**
|
|
* Returns a regular expression used to trigger a tooltip.
|
|
* Normally, tooltips after a scheduled analysis has been completed.
|
|
* To avoid delays, this function can be used to trigger
|
|
* analysis & tooltip fetching early.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement tooltips.
|
|
* Default implementation returns null.
|
|
*
|
|
* @return RegExp
|
|
*/
|
|
getTooltipRegex: function() {
|
|
return null;
|
|
},
|
|
|
|
/**
|
|
* Extends the default caching strategy for code completion.
|
|
* Implementors should return a regular expression used to determine if
|
|
* whether completions can be cached. If the prefix of the current line
|
|
* matches this regular expression, this tells the completion engine that it
|
|
* is allowed to reuse any completions cached at the start of this prefix.
|
|
* Without this, caching also performed but only based on
|
|
* {@link #getIdentifierRegex()}.
|
|
*
|
|
* As an example, consider a scenario where the user just typed
|
|
*
|
|
* ```
|
|
* if (i
|
|
* ```
|
|
*
|
|
* If completion proposals were suggested at the start of the line,
|
|
* and the complretion cache regex matches "if (", then Cloud9 will
|
|
* use those completions rather than recompute them. With this optimization,
|
|
* it's possible to use caching to such an extent that even for longer
|
|
* statements like `if (foo === bar`, completions only need to be computed
|
|
* once.
|
|
*
|
|
* Warning: this is an expert feature that helps optimize the caching
|
|
* strategy of the code completion engine. Implemented incorrectly, it can
|
|
* make completions appear in places they shouldn't or may cause completions
|
|
* to go missing.
|
|
*
|
|
*
|
|
*
|
|
* Example implementation for JavaScript:
|
|
*
|
|
* ```
|
|
* completer.getCacheCompletionRegex = function() {
|
|
* // Match strings that can be an expression or its prefix
|
|
* return new RegExp(
|
|
* // 'if/while/for ('
|
|
* "(\\b(if|while|for|switch)\\s*\\("
|
|
* // other identifiers and keywords without (
|
|
* + "|\\b\\w+\\s+"
|
|
* // equality operators, operators such as + and -,
|
|
* // and opening brackets { and [
|
|
* + "|(==|!=|[-+]=|[-+*%<>?!|&{[])"
|
|
* // spaces
|
|
* + "|\\s)+"
|
|
* );
|
|
* };
|
|
* ```
|
|
*
|
|
* which matches strings such as "if (", "while (", and "x + ".
|
|
*
|
|
* MAY be overridden by inheritors that implement code completion.
|
|
*
|
|
* @return RegExp
|
|
*/
|
|
getCacheCompletionRegex: function() {
|
|
return null;
|
|
},
|
|
|
|
// PARSING AND ABSTRACT SYNTAX CALLBACKS
|
|
|
|
/**
|
|
* Parses the given document.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement parsing
|
|
* (which is, like all features here, optional).
|
|
*
|
|
* @param {String} docValue the source the document to analyze
|
|
* @param {Object} options options
|
|
* @return {Object} an abstract syntax tree (of any type), or null if not implemented
|
|
*/
|
|
parse: function(docValue, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Finds a tree node at a certain row and column,
|
|
* e.g. using the findNode(pos) function of treehugger.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement parsing.
|
|
*
|
|
* @param {Object} ast An abstract syntax tree object from {@link #parse}
|
|
* @param {Object} pos The position of the node to look up
|
|
* @param {Number} pos.row The position's row
|
|
* @param {Number} pos.column The position's column
|
|
* @param {Function} callback The callback for the result
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} [callback.result] The found node
|
|
*/
|
|
findNode: function(ast, pos, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Returns the a tree node at a certain row and col,
|
|
* e.g. using the node.getPos() function of treehugger.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement parsing.
|
|
*
|
|
* @param {Object} node The node to look up
|
|
* @param {Function} callback The callback for the result
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} [callback.result] The resulting position
|
|
* @param {Number} callback.result.sl The starting line
|
|
* @param {Number} callback.result.el The ending line
|
|
* @param {Number} callback.result.sc The starting column
|
|
* @param {Number} callback.result.ec The ending column
|
|
*/
|
|
getPos: function(node, callback) {
|
|
callback();
|
|
},
|
|
|
|
// OTHER CALLBACKS
|
|
|
|
/**
|
|
* Initialize this language handler.
|
|
*
|
|
* MAY be overridden by inheritors.
|
|
*
|
|
* @param callback The callback; must be called
|
|
*/
|
|
init: function(callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when the document has been updated (possibly after a certain delay)
|
|
*
|
|
* MAY be overridden by inheritors.
|
|
*
|
|
* @param {Document} doc The current document
|
|
* @param {Function} callback The callback; must be called
|
|
*/
|
|
onUpdate: function(doc, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when a new document has been opened.
|
|
*
|
|
* MAY be overridden by inheritors.
|
|
*
|
|
* @param {String} path The path of the newly opened document
|
|
* @param {String} doc The Document object representing the source
|
|
* @param {String} oldPath The path of the document that was active before
|
|
* @param {Function} callback The callback; must be called
|
|
*/
|
|
onDocumentOpen: function(path, doc, oldPath, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when a document is closed in the IDE.
|
|
*
|
|
* MAY be overridden by inheritors.
|
|
*
|
|
* @param {String} path the path of the file
|
|
* @param {Function} callback The callback; must be called
|
|
*/
|
|
onDocumentClose: function(path, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when the cursor has been moved.
|
|
*
|
|
* MAY be overridden by inheritors that immediately act upon cursor moves.
|
|
*
|
|
* See {@link #tooltip} and {@link #highlightOccurrences}
|
|
* for handler functions that are invoked after the cursor has been moved,
|
|
* the document has been analyzed, and feedback is requested.
|
|
*
|
|
* @param {Document} doc Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if parsed already, otherwise null)
|
|
* @param {Object} cursorPos The current cursor position
|
|
* @param {Number} cursorPos.row The current cursor's row
|
|
* @param {Number} cursorPos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented and if parsed already, otherwise null)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @paran {Object} callback.result An optional result. Supports the same result objects as
|
|
* {@link #tooltip} and {@link #highlightOccurrences}
|
|
*/
|
|
onCursorMove: function(doc, ast, cursorPos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when the cursor has been moved inside to a different AST node.
|
|
* Gets a tooltip to display when the cursor is moved to a particular location.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement tooltips.
|
|
*
|
|
* See {@link #getTooltipRegex} for setting a regular expression to trigger
|
|
* tooltips early.
|
|
*
|
|
* @param {Document} doc Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} cursorPos The current cursor position
|
|
* @param {Number} cursorPos.row The current cursor's row
|
|
* @param {Number} cursorPos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result
|
|
* @param {Object|String} callback.result.hint An object or HTML string with the tooltip to display
|
|
* @param {Object[]} [callback.result.signatures] One or more function signatures to show
|
|
* @param {String} callback.result.signatures.name Function name
|
|
* @param {String} [callback.result.signatures.doc] Function documentation, as text
|
|
* @param {String} [callback.result.signatures.docHtml]
|
|
* Function documentation, as HTML
|
|
* @param {Object[]} callback.result.signatures.parameters
|
|
* Function parameters
|
|
* @param {String} callback.result.signatures.parameters.name
|
|
* Parameter name
|
|
* @param {String} [callback.result.signatures.parameters.type]
|
|
* Parameter type
|
|
* @param {String} [callback.result.signatures.parameters.doc]
|
|
* Parameter documentation, as text
|
|
* @param {String} [callback.result.signatures.parameters.docHtml]
|
|
* Parameter documentation, as HTML
|
|
* @param {String} [callback.result.signatures.returnType]
|
|
* The function return type
|
|
* @param {Object} callback.result.pos The position range for which this tooltip is valid
|
|
* @param {Number} callback.result.pos.sl The starting line
|
|
* @param {Number} callback.result.pos.el The ending line
|
|
* @param {Number} callback.result.pos.sc The starting column
|
|
* @param {Number} callback.result.pos.ec The ending column
|
|
* @param {Object} [callback.result.displayPos] The position to display this tooltip
|
|
* @param {Number} [callback.result.displayPos.row] The display position's row
|
|
* @param {Number} [callback.result.displayPos.column] The display position's column
|
|
*/
|
|
tooltip: function(doc, ast, cursorPos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Gets the instances to highlight when the cursor is moved to a particular location.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement occurrence highlighting.
|
|
*
|
|
* @param {Document} doc Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} cursorPos The current cursor position
|
|
* @param {Number} cursorPos.row The current cursor's row
|
|
* @param {Number} cursorPos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result
|
|
* @param {Object[]} [callback.result.markers] The occurrences to highlight
|
|
* @param {Object} callback.result.markers.pos The marker's position
|
|
* @param {Number} callback.result.markers.pos.sl The starting line
|
|
* @param {Number} callback.result.markers.pos.el The ending line
|
|
* @param {Number} callback.result.markers.pos.sc The starting column
|
|
* @param {Number} callback.result.markers.pos.ec The ending column
|
|
* @param {Boolean} callback.result.isGeneric Indicates this is generic highlighting and should be deferred
|
|
* @param {"occurrence_other"|"occurrence_main"} callback.result.markers.type
|
|
* The type of occurrence: the main one, or any other one.
|
|
*/
|
|
highlightOccurrences: function(doc, ast, cursorPos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Determines what refactorings to enable when the cursor is moved to a particular location.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement refactorings.
|
|
*
|
|
* @param {Document} doc Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} cursorPos The current cursor position
|
|
* @param {Number} cursorPos.row The current cursor's row
|
|
* @param {Number} cursorPos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result
|
|
* @param {String[]} callback.result.refactorings
|
|
* The refactorings to enable, such as "rename"
|
|
* @param {String[]} [callback.result.isGeneric]
|
|
* Whether is a generic answer and should be deferred
|
|
*/
|
|
getRefactorings: function(doc, ast, cursorPos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Constructs an outline.
|
|
*
|
|
* Example outline object:
|
|
*
|
|
* {
|
|
* icon: 'method',
|
|
* name: "fooMethod",
|
|
* pos: this.getPos(),
|
|
* displayPos: { sl: 15, sc: 20 },
|
|
* items: [ ...items nested under this method... ],
|
|
* isUnordered: true
|
|
* }
|
|
*
|
|
* SHOULD be overridden by inheritors that implement an outline.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result, a JSON outline structure or null if not supported
|
|
* @param {"event"|"method"|"method2"|"package"|"property"|"property2"|"unknown"|"unknown2"} callback.result.icon
|
|
* The icon to display for the first outline item
|
|
* @param {String} callback.result.name The name to display for the first outline item
|
|
* @param {Object} callback.result.pos The item's range, e.g. the full visible range of a method
|
|
* @param {Number} callback.result.pos.sl The item's starting row
|
|
* @param {Number} [callback.result.pos.el] The item's ending row
|
|
* @param {Number} [callback.result.pos.sc] The item's starting column
|
|
* @param {Number} [callback.result.pos.ec] The item's ending column
|
|
* @param {Object} [callback.result.displayPos] The item's position of the text to select when it's picked from the outline
|
|
* @param {Number} callback.result.displayPos.sl The item's starting row
|
|
* @param {Number} [callback.result.displayPos.el] The item's ending row
|
|
* @param {Number} [callback.result.displayPos.sc] The item's starting column
|
|
* @param {Number} [callback.result.displayPos.ec] The item's ending column
|
|
* @param {Object[]} callback.result.items Any items nested under the curent item.
|
|
* @param {Boolean} [callback.result.isGeneric] Indicates that this is a generic, language-independent outline
|
|
* @param {Boolean} [callback.result.isUnordered] Indicates the outline is not ordered by appearance of the items,
|
|
* but that they're e.g. grouped as methods, properties, etc.
|
|
*/
|
|
outline: function(doc, ast, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Constructs a hierarchy.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement a type hierarchy.
|
|
*
|
|
* @ignore Not supported right now.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} cursorPos The current cursor position
|
|
* @param {Number} cursorPos.row The current cursor's row
|
|
* @param {Number} cursorPos.column The current cursor's column
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result A JSON hierarchy structure or null if not supported
|
|
*/
|
|
hierarchy: function(doc, cursorPos, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Performs code completion for the user based on the current cursor position.
|
|
*
|
|
* MUST be overridden by inheritors that implement code completion.
|
|
*
|
|
* Example completion result:
|
|
* {
|
|
* name : "foo()",
|
|
* replaceText : "foo()",
|
|
* icon : "method",
|
|
* meta : "FooClass",
|
|
* doc : "The foo() method",
|
|
* docHead : "FooClass.foo",
|
|
* priority : 1
|
|
* };
|
|
*
|
|
* See also {@link #getCompletionRegex}.
|
|
* See also {@link #predictNextCompletion}.
|
|
* See also {@link language.worker_util#execAnalysis} for invoking a code
|
|
* completion tool that runs in the workspace.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path
|
|
* @param {String} options.language The current language
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {String} options.line The current line
|
|
* @param {String} options.identifierPrefix
|
|
* The current identifier up to the cursor position
|
|
* @param {Boolean} options.noDoc Docs are not requested at this time and may
|
|
* be left out as an optimization. Please set `noDoc: true`
|
|
* for any completions where docs are left out so
|
|
* another `complete()` request can be fired to retrieve their docs.
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result, an array of completion matches
|
|
* @param {String} [callback.result.replaceText]
|
|
* The text to replace the selection with
|
|
* @param {String} callback.result.name
|
|
* The full name to show in the completion popup
|
|
* @param {String} [callback.result.id] The short name that identifies this completion
|
|
* @param {"event"|"method"|"method2"|"package"|"property"|"property2"|"unknown"|"unknown2"} [callback.result.icon]
|
|
* The icon to use
|
|
* @param {String} callback.result.meta Additional information to show
|
|
* @param {String} [callback.result.doc] Documentation to display
|
|
* @param {Boolean} [callback.result.noDoc]
|
|
* Boolean indicating that documentation may be available for
|
|
* this completion but was not included as options.noDoc was
|
|
* set. See options.noDoc.
|
|
* @param {String} [callback.result.docHead]
|
|
* Documentation heading to display
|
|
* @param {Boolean} [callback.result.guessTooltip]
|
|
* Try to guess a tooltip based on this completion.
|
|
* @param {Number} [callback.result.priority]
|
|
* Priority of this completion suggestion
|
|
* @param {Boolean} [callback.result.isGeneric]
|
|
* Indicates that this is a generic, language-independent
|
|
* suggestion
|
|
* @param {Boolean} [callback.result.isContextual]
|
|
* Indicates that this is a contextual completion,
|
|
* and that any generic completions should not be shown
|
|
*/
|
|
complete: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Adds pre-caching or predictions to the code completer,
|
|
* by predicting how to do the next completion after the
|
|
* current one as the user keeps typing.
|
|
*
|
|
* An example implementation for JavaScript returns the current
|
|
* completion plus a dot:
|
|
*
|
|
* ```
|
|
* handler.predictNextCompletion = function(doc, ast, pos, options, callback) {
|
|
* // Only predict if we have exactly one available completion
|
|
* if (options.matches.length !== 1)
|
|
* return callback();
|
|
* // Return that completion plus a dot
|
|
* callback(null, { predicted: predicted[0] + "." });
|
|
* };
|
|
* ```
|
|
*
|
|
* To understand how the above works, consider the following scenario:
|
|
*
|
|
* ```
|
|
* var foo = { bar: 2 };
|
|
* fo
|
|
* ```
|
|
*
|
|
* So we can predict that the current identifier `fo` will expand to `foo`.
|
|
* That means that the next interesting code completion may relate to `foo.`.
|
|
* Predicting this allows us to precompute those completions rather than
|
|
* wait until the user types the next character(s).
|
|
*
|
|
* For the above scenario, our function is called with the following arguments:
|
|
*
|
|
* ```
|
|
* predictNextCompletion(doc, ast, pos, {
|
|
* matches: [{
|
|
* name: "foo",
|
|
* replaceText: "foo"
|
|
* }]
|
|
* })
|
|
* ```
|
|
*
|
|
* So all our function has to do is return "foo." and we're on
|
|
* our way to predict the future!
|
|
*
|
|
* Below is a more sophisticated example which filters the current completions
|
|
* before making a prediction:
|
|
*
|
|
* ```
|
|
* handler.predictNextCompletion = function(doc, ast, pos, options, callback) {
|
|
* // We look at all current completion proposals, but first filter for
|
|
* // contextual completions and ignore any keyword predictions
|
|
* var predicted = options.matches.filter(function(m) {
|
|
* return m.isContextual && !m.replaceText.match(KEYWORD_REGEX);
|
|
* });
|
|
* // Let's predict only if we have exactly one proposal left over to
|
|
* // make a prediction for (e.g., we know the user is going to type "foo")
|
|
* if (predicted.length !== 1)
|
|
* return callback();
|
|
* // Predict that the current user is going to type this identifier
|
|
* // followed by a dot (e.g., "foo.")
|
|
* callback(null, { predicted: predicted[0] + "." });
|
|
* };
|
|
* ```
|
|
*
|
|
* Use the showEarly property to show the predicted completions immediately
|
|
* to users, e.g. show `this.foo` when the user types `th`. Only
|
|
* completions marked "isContextual" are shown in this fashion.
|
|
*
|
|
* MAY be overridden by inheritors that implement code completion.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The most recent completion AST node (if parse() is implemented)
|
|
* @param {Object} options.matches The most recent completion matches
|
|
* @param {String} options.path The current path
|
|
* @param {String} options.language The current language
|
|
* @param {String} options.line The current line
|
|
* @param {String} options.identifierPrefix
|
|
* The current identifier up to the cursor position
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result, an array of completion matches
|
|
* @param {String} callback.result.predicted
|
|
* The predicted text for which to try completion
|
|
* @param {Boolean} callback.result.showEarly
|
|
* Show the prediction as part of the completion
|
|
* results immediately (e.g., to show this.foo
|
|
* when the user types 'th')
|
|
*/
|
|
predictNextCompletion: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Analyzes an AST or file and annotates it as desired.
|
|
*
|
|
* Example of an annotation to return:
|
|
*
|
|
* {
|
|
* pos: { sl: 1, el: 1, sc: 4, ec: 5 },
|
|
* type: "warning",
|
|
* message: "Assigning to undeclared variable."
|
|
* }
|
|
*
|
|
* SHOULD be overridden by inheritors that implement analysis.
|
|
*
|
|
* See also {@link language.worker_util#execAnalysis} for invoking a code
|
|
* completion tool that runs in the workspace.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Boolean} [options.minimalAnalysis] Fast, minimal analysis is requested, e.g.
|
|
* for code completion or tooltips.
|
|
* @param {Object[]} callback.result The function's result, an array of error and warning markers
|
|
* @param {Object} callback.result.pos The current cursor position
|
|
* @param {Number} callback.result.pos.row The current cursor's row
|
|
* @param {Number} callback.result.pos.column The current cursor's column
|
|
* @param {String} callback.result.type The type of warning, i.e., "error", "warning", or "info"
|
|
* @param {String} callback.result.message The message of the warning, i.e., "error", "warning", or "info"
|
|
* @param {Boolean} [callback.result.quickfix] Whether there is a quickfix available for this marker
|
|
*/
|
|
analyze: function(doc, ast, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Gets all positions to select for a rename refactoring.
|
|
*
|
|
* Example result, renaming a 3-character identfier
|
|
* on line 10 that also occurs on line 11 and 12:
|
|
*
|
|
* {
|
|
* length: 3,
|
|
* pos: {
|
|
* row: 10,
|
|
* column: 5
|
|
* },
|
|
* others: [
|
|
* { row: 11, column: 5 },
|
|
* { row: 12, column: 5 }
|
|
* ]
|
|
* }
|
|
*
|
|
* MUST be overridden by inheritors that implement rename refactoring.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The function's result (see function description).
|
|
* @param {Boolean} callback.result.isGeneric Indicates this is a generic refactoring and should be deferred.
|
|
* @param {Boolean} callback.result.length The lenght of the rename identifier
|
|
* @param {Object} callback.result.pos The position of the current identifier
|
|
* @param {Number} callback.result.pos.row The row of the current identifier
|
|
* @param {Number} callback.result.pos.column The column of the current identifier
|
|
* @param {Object[]} callback.result.others The positions of other identifiers to be renamed
|
|
* @param {Number} callback.result.others.row The row of another identifier to be renamed
|
|
* @param {Number} callback.result.others.column The column of another identifier to be renamed
|
|
*/
|
|
getRenamePositions: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when refactoring is started.
|
|
*
|
|
* MAY be overridden by inheritors that implement rename refactoring.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Function} callback The callback; must be called
|
|
*/
|
|
onRenameBegin: function(doc, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Confirms that a rename refactoring is valid, before committing it.
|
|
*
|
|
* MAY be overridden by inheritors that implement rename refactoring.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} oldId The old identifier was being renamed
|
|
* @param {Number} oldId.row The row of the identifier that was being renamed
|
|
* @param {Number} oldId.column The column of the identifier that was being renamed
|
|
* @param {String} oldId.value The value of the identifier that was being renamed
|
|
* @param {String} newName The new name of the element after refactoring
|
|
* @param {Boolean} isGeneric True if this was a refactoring marked with 'isGeneric' (see {@link #getRenamePositions})
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Null if the refactoring can be committed, or an error message if refactoring failed
|
|
*/
|
|
commitRename: function(doc, oldName, newName, isGeneric, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Invoked when a refactor request is cancelled
|
|
*
|
|
* MAY be overridden by inheritors that implement rename refactoring.
|
|
*
|
|
* @param {Function} callback The callback; must be called
|
|
*/
|
|
onRenameCancel: function(callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Performs code formatting.
|
|
*
|
|
* MUST be overridden by inheritors that implement code formatting.
|
|
*
|
|
* @param {Document} doc the Document object representing the source
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {String} callback.result The source code after formatting
|
|
*/
|
|
codeFormat: function(doc, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Performs jumping to a definition.
|
|
*
|
|
* MUST be overridden by inheritors that implement jump to definition.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Object} options Options
|
|
* @param {String} options.path The current file path.
|
|
* @param {Object} options.node The current AST node (if parse() is implemented)
|
|
* @param {String} options.language The current language
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object[]} callback.results The results
|
|
* @param {String} [callback.results.path]
|
|
* The result path
|
|
* @param {Number} [callback.results.row]
|
|
* The result row
|
|
* @param {Number} [callback.results.column]
|
|
* The result column
|
|
* @param {"event"|"method"|"method2"|"package"|"property"|"property2"|"unknown"|"unknown2"} [callback.results.icon]
|
|
* The icon to display (in case of multiple results)
|
|
* @param {Boolean} [callback.results.isGeneric]
|
|
* Indicates that this is a generic, language-independent
|
|
* suggestion (that should be deferred)
|
|
*/
|
|
jumpToDefinition: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Gets quickfixes for a position (also referred to "quick assists" when
|
|
* there is no error).
|
|
*
|
|
* Note that there is currently no UI for this feature,
|
|
* we just have a keyboard shortcut.
|
|
*
|
|
* MUST be overridden by inheritors that implement quickfixes.
|
|
*
|
|
* Example result:
|
|
*
|
|
* ```
|
|
* var Range = new require("ace/range").Range;
|
|
* var result = {
|
|
* message: "Insert missing semicolon",
|
|
* image: "semicolon.png",
|
|
* preview: ";",
|
|
* deltas: [{
|
|
* action: "insert",
|
|
* start: { row: row, column: column },
|
|
* end: { row: row, column: column },
|
|
* lines: [";"]
|
|
* }],
|
|
* pos: { row: row, column: column + 1 }
|
|
* };
|
|
* ```
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object[]} callback.result The function's result
|
|
* @param {String} [callback.result.message] Short description, to be displayed in the list of resolutions, as text
|
|
* @param {String} [callback.result.messageHtml] Short description, to be displayed in the list of resolutions, as HTML
|
|
* @param {String} [callback.result.image] Image to be displayed in the list of resolutions
|
|
* @param {String} [callback.result.preview]
|
|
* @param {String} [callback.result.previewHtml]
|
|
* @param {Object[]} callback.result.deltas An array of Ace delta objects
|
|
* @param {String} callback.result.deltas.action The action, i.e. insert or remove.
|
|
* @param {Object} callback.result.deltas.start.row
|
|
* @param {Object} callback.result.deltas.start.column
|
|
* @param {Object} callback.result.deltas.end.row
|
|
* @param {Object} callback.result.deltas.end.column
|
|
* @param {String} [callback.result.deltas.path] The file path to apply this delta to
|
|
* @param {String[]} [callback.result.deltas.lines]
|
|
* @param {Object} [callback.result.pos] The position where the cursor should be after applying
|
|
*/
|
|
getQuickfixes: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
},
|
|
|
|
/**
|
|
* Given the cursor position and the parsed node at that position,
|
|
* gets the string to send to the debugger for live inspect hovering.
|
|
*
|
|
* SHOULD be overridden by inheritors that implement a debugger
|
|
* with live inspect. If not implemented, the string value based on
|
|
* options's position is used.
|
|
*
|
|
* @param {Document} doc The Document object representing the source
|
|
* @param {Object} ast The entire AST of the current file (if any)
|
|
* @param {Object} pos The current cursor position
|
|
* @param {Number} pos.row The current cursor's row
|
|
* @param {Number} pos.column The current cursor's column
|
|
* @param {Function} callback The callback; must be called
|
|
* @param {Error|String} callback.err Any resulting error
|
|
* @param {Object} callback.result The resulting expression
|
|
* @param {String} callback.result.value The string representation of the expression to inspect
|
|
* @param {Object} callback.result.pos The expression's position
|
|
* @param {Number} callback.result.pos.sl The expression's starting row
|
|
* @param {Number} callback.result.pos.el The expression's ending row
|
|
* @param {Number} callback.result.pos.sc The expression's starting column
|
|
* @param {Number} callback.result.pos.ec The expression's ending column
|
|
*/
|
|
getInspectExpression: function(doc, ast, pos, options, callback) {
|
|
callback();
|
|
}
|
|
};
|
|
|
|
// Mark all abstract/builtin methods for later optimization
|
|
for (var f in module.exports) {
|
|
if (typeof module.exports[f] === "function")
|
|
module.exports[f].base_handler = true;
|
|
}
|
|
|
|
});
|