docs/language-server/protocol-language-server.md
This document contains the specification of the Enso protocol messages that pertain to the language server component. Please familiarise yourself with the common features of the protocol before reading this document.
For information on the design and architecture of the protocol, as well as its transport formats, please look here.
<!-- MarkdownTOC levels="2,3" autolink="true" -->ExpressionIdContextIdStackItemMethodCallMethodPointerProfilingInfoExecutionEnvironmentExpressionConfigExpressionUpdateExpressionUpdatePayloadVisualizationConfigurationVisualizationExpressionSuggestionEntryArgumentSuggestionEntrySuggestionEntryTypeSuggestionIdDocSectionSuggestionsDatabaseEntryFieldActionFieldUpdateSuggestionArgumentUpdateSuggestionsDatabaseUpdateSuggestionsOrderDatabaseUpdateExportFileDirectoryTreeFileAttributesUTCDateTimeFileEventKindPositionRangeTextEditDiagnosticTypeStackTraceElementExecutionResultDiagnosticSHA3-224FileEditFileContentsFileSystemObjectWorkspaceEditEnsoDigestFileSegmentContentRootLibraryEntryLibraryVersionContactEditionReferenceLibraryComponentGroupsLibraryComponentGroupLibraryComponentexecutionContext/createexecutionContext/destroyexecutionContext/forkexecutionContext/pushexecutionContext/popexecutionContext/recomputeexecutionContext/interruptexecutionContext/setExecutionEnvironmentexecutionContext/getComponentGroupsexecutionContext/expressionUpdatesexecutionContext/executionFailedexecutionContext/executionCompleteexecutionContext/executionStatusexecutionContext/executeExpressionexecutionContext/attachVisualizationexecutionContext/detachVisualizationexecutionContext/modifyVisualizationexecutionContext/visualizationUpdateexecutionContext/visualizationEvaluationFailededitions/listAvailableeditions/resolveeditions/getProjectSettingseditions/setProjectParentEditioneditions/setProjectLocalLibrariesPreferenceeditions/listDefinedLibrarieseditions/listDefinedComponentslibrary/listLocallibrary/createlibrary/getMetadatalibrary/setMetadatalibrary/getPackagelibrary/publishlibrary/preinstallErrorAccessDeniedErrorFileSystemErrorContentRootNotFoundErrorFileNotFoundFileExistsOperationTimeoutErrorNotDirectoryNotFileCannotOverwriteReadOutOfBoundsCannotDecodeStackItemNotFoundErrorContextNotFoundErrorEmptyStackErrorInvalidStackItemErrorModuleNotFoundErrorVisualizationNotFoundErrorVisualizationExpressionErrorFileNotOpenedErrorTextEditValidationErrorInvalidVersionErrorWriteDeniedErrorCapabilityNotAcquiredSessionNotInitialisedErrorSessionAlreadyInitialisedErrorResourcesInitializationErrorSuggestionsDatabaseErrorProjectNotFoundErrorModuleNameNotResolvedErrorSuggestionNotFoundErrorEditionNotFoundErrorLibraryAlreadyExistsLibraryRepositoryAuthenticationErrorLibraryPublishErrorLibraryUploadErrorLibraryDownloadErrorLocalLibraryNotFoundLibraryNotResolvedInvalidLibraryNameDependencyDiscoveryErrorInvalidSemverVersionExpressionNotFoundErrorFailedToApplyEditsRefactoringNotSupportedProjectRenameFailedDefinitionAlreadyExistsThere are a number of types that are used only within the language server's protocol messages. These are specified here.
ExpressionIdAn identifier used for Enso expressions.
type ExpressionId = UUID;
ContextIdAn identifier used for execution contexts.
type ContextId = UUID;
StackItemA representation of an executable position in code, used by the execution APIs.
ExplicitCall is a call performed at the top of the stack, to initialize the
context with first execution. The thisArgumentsPosition field can be omitted,
in which case the context will try to infer the argument on a best-effort basis.
E.g. for a module-level method, or a method defined on a parameter-less type,
self will be substituted for the unambiguous singleton instance.
LocalCall is a call corresponding to "entering a function call".
type StackItem = ExplicitCall | LocalCall;
interface ExplicitCall {
methodPointer: MethodPointer;
thisArgumentExpression?: string;
positionalArgumentsExpressions: string[];
}
interface LocalCall {
expressionId: ExpressionId;
}
MethodCallA representation of a method call.
interface MethodCall {
/** The method pointer of a call. */
methodPointer: MethodPointer;
/** Indexes of arguments that have not been applied to this method. */
notAppliedArguments: number[];
}
MethodPointerPoints to a method definition.
interface MethodPointer {
/** The fully qualified module name. */
module: string;
/** The type on which the method is defined. */
definedOnType: string;
/** The method name. */
name: string;
}
ProfilingInfoProfiling information on an executed expression. It is implemented as a union as additional types of information will be added in the future.
type ProfilingInfo = ExecutionTime;
Where:
interface ExecutionTime {
/** The time elapsed during the expression's evaluation, in nanoseconds. */
nanoTime: number;
}
ExecutionEnvironmentThe execution environment of Enso runtime.
type ExecutionEnvironment = Design | Live;
ExpressionConfigThe expression configuration used in the recompute request.
interface ExpressionConfig {
/** The expression identifier. */
expressionId: ExpressionId;
/** The execution environment that should be used to run this expression. */
executionEnvironment?: ExecutionEnvironment;
}
ExpressionUpdateAn update about the computed expression.
interface ExpressionUpdate {
/** The id of updated expression. */
expressionId: ExpressionId;
/** The updated type of the expression.
*
* Possible values:
* - empty array indicates no type information for this expression
* - array with a single value contains a value of this expression
* - array with multiple values represents an intersetion type
*/
type: string[];
/**
* The list of types this expression can be converted to.
*/
hiddenType: string[];
/** The updated method call info. */
methodCall?: MethodCall;
/** Profiling information about the expression. */
profilingInfo: ProfilingInfo[];
/** Whether the expression's value came from the cache. */
fromCache: boolean;
/** An extra information about the computed value. */
payload: ExpressionUpdatePayload;
}
ExpressionUpdatePayloadAn information about the computed value.
type ExpressionUpdatePayload = Value | DataflowError | Panic | Pending;
/** Indicates that the expression was computed to a value. */
interface Value {
/** Information about attached warnings. */
warnings?: Warnings;
/** The schema of returned function value. */
functionSchema?: FunctionSchema;
}
/** Indicates that the expression was computed to an error. */
interface DataflowError {
/** The list of expressions leading to the root error. */
trace: ExpressionId[];
}
/** Indicates that the expression failed with the runtime exception. */
interface Panic {
/** The error message. */
message: string;
/** The stack trace. */
trace: ExpressionId[];
}
/** Indicates the expression is currently being computed. Optionally it
* provides a description and fraction of completion (`0.0-1.0`). */
interface Pending {
/** Optional message describing current operation. */
message?: string;
/** Optional amount of already done work as a number between `0.0` to `1.0`.
*/
progress?: number;
/** Indicates whether the computation of the expression has been interrupted and will be retried. */
wasInterrupted: boolean;
}
/** Information about warnings associated with the value. */
interface Warnings {
/** The number of attached warnings. */
count: number;
/** If the value has a single warning attached, this field contains textual
* representation of the attached warning. In general, warning values should
* be obtained by attaching an appropriate visualization to a value. */
value?: string;
}
/** Contains a method pointer with information on the partially applied argument
* positions. */
interface FunctionSchema {
/** The method pointer of this function. */
methodPointer: MethodPointer;
/** Indexes of arguments that have not been applied to this function. */
notAppliedArguments: number[];
}
VisualizationConfigurationA configuration object for properties of the visualization.
interface VisualizationConfiguration {
/** An execution context of the visualization. */
executionContextId: UUID;
/** The qualified name of the module to be used to evaluate the arguments for
* the visualization expression. */
visualizationModule: string;
/** An expression that creates a visualization. */
expression: string | MethodPointer;
/** A list of arguments to pass to the visualization expression. */
positionalArgumentsExpressions?: string[];
}
SuggestionEntryArgumentThe argument of a SuggestionEntry.
// The argument of a constructor, method or function suggestion.
interface SuggestionEntryArgument {
/** The argument name. */
name: string;
/** The argument type. String 'Any' is used to specify generic types. */
reprType: string;
/** Indicates whether the argument is lazy. */
isSuspended: boolean;
/** Indicates whether the argument has default value. */
hasDefault: boolean;
/** Optional default value. */
defaultValue?: string;
/** Optional list of possible values that this argument takes. */
tagValues?: string[];
}
SuggestionEntryThe language construct that can be returned as a suggestion.
// The definition scope
interface SuggestionEntryScope {
// The start position of the definition scope
start: Position;
// The end position of the definition scope
end: Position;
}
// A type of suggestion entries.
type SuggestionEntry =
// A module
| Module
// A type
| Type
// A type constructor
| Constructor
// A method defined on a type
| Method
// A function
| Function
// A local value
| Local;
interface Module {
/** The fully qualified module name. */
module: string;
/** The documentation string. */
documentation?: string;
/** The fully qualified module name re-exporting this module.
*
* @deprecated use reexports field instead
*/
reexport?: string;
/** The list of fully qualified module names re-exporting this module. */
reexports: string[];
}
interface Type {
/** The external id. */
externalId?: UUID;
/** The type name. */
name: string;
/** The qualified module name where the type is defined. */
module: string;
/** The list of type parameters. */
params: SuggestionEntryArgument[];
/** Qualified name of the parent type. */
parentType?: string;
/** The fully qualified module name re-exporting this type.
*
* @deprecated use reexports field instead
*/
reexport?: string;
/** The list of fully qualified module names re-exporting this type. */
reexports: string[];
/** The documentation string. */
documentation?: string;
}
interface Constructor {
/** The external id. */
externalId?: UUID;
/** The constructor name. */
name: string;
/** The qualified module name where this constructor is defined. */
module: string;
/** The list of arguments. */
arguments: SuggestionEntryArgument[];
/** The type of the constructor. */
returnType: string;
/** The fully qualified module name re-exporting this constructor.
*
* @deprecated use reexports field instead
*/
reexport?: string;
/** The list of fully qualified module names re-exporting this constructor. */
reexports: string[];
/** The documentation string. */
documentation?: string;
/** The list of annotations. */
annotations: string[];
}
interface Method {
/** The external id. */
externalId?: UUID;
/** The method name. */
name: string;
/** The module name where this method is defined. */
module: string;
/** The list of arguments. */
arguments: SuggestionEntryArgument[];
/** The method self type. */
selfType: string;
/** The return type of this method. */
returnType: string;
/** The flag indicating whether this method is static or instance. */
isStatic: boolean;
/** The fully qualified module name re-exporting this method.
*
* @deprecated use reexports field instead
*/
reexport?: string;
/** The list of fully qualified module names re-exporting this method. */
reexports: string[];
/** The documentation string. */
documentation?: string;
/** The list of annotations. */
annotations: string[];
}
interface Function {
/** The external id. */
externalId?: UUID;
/** The function name. */
name: string;
/** The module name where this function is defined. */
module: string;
/** The list of arguments. */
arguments: SuggestionEntryArgument[];
/** The function return type. */
returnType: string;
/** The scope where the function is defined. */
scope: SuggestionEntryScope;
/** The documentation string. */
documentation?: string;
}
interface Local {
/** The external id. */
externalId?: UUID;
/** The name of a value. */
name: string;
/** The module where this value is defined. */
module: string;
/** The type of a value. */
returnType: string;
/** The scope where the value is defined. */
scope: SuggestionEntryScope;
/** The documentation string. */
documentation?: string;
}
SuggestionEntryTypeThe suggestion entry type that is used as a filter in search requests.
// The kind of a suggestion.
type SuggestionEntryType =
| Module
| Type
| Constructor
| Method
| Function
| Local;
SuggestionIdThe suggestion entry id of the suggestions database.
type SuggestionId = number;
SuggestionsDatabaseEntryThe entry in the suggestions database.
interface SuggestionsDatabaseEntry {
/** The suggestion entry id. */
id: SuggestionId;
/** The suggestion entry. */
suggestion: SuggestionEntry;
}
FieldActionThe modifying action on a record field.
type FieldAction = "Remove" | "Set";
FieldUpdateAn object representing a modification of a field in a record.
interface FieldUpdate<T> {
/** The modifying action. */
tag: FieldAction;
/** The updated value. */
value?: T;
}
SuggestionArgumentUpdateAn operation applied to the suggestion argument.
type SuggestionArgumentUpdate =
| SuggestionArgumentAdd
| SuggestionArgumentRemove
| SuggestionArgumentModify;
interface SuggestionArgumentAdd {
/** The position of the argument. */
index: int;
/** The argument to add. */
argument: SuggestionEntryArgument;
}
interface SuggestionArgumentRemove {
/** The position of the argument. */
index: int;
}
interface SuggestionArgumentModify {
/** The position of the argument. */
index: int;
/** The new name. */
name?: FieldUpdate<string>;
/** The new argument type. */
reprType?: FieldUpdate<string>;
/** The new `isSuspended` flag. */
isSuspended?: FieldUpdate<boolean>;
/** The new `hasDefault` flag. */
hasDefault?: FieldUpdate<boolean>;
/** The new default value. */
defaultValue?: FieldUpdate<string>;
}
SuggestionsDatabaseUpdateThe update of the suggestions database.
/** The kind of the suggestions database update. */
type SuggestionsDatabaseUpdate =
| SuggestionsDatabaseUpdateAdd
| SuggestionsDatabaseUpdateRemove
| SuggestionsDatabaseUpdateModify;
interface SuggestionsDatabaseUpdateAdd {
/** Suggestion entry id. */
id: SuggestionId;
/** Suggestion entry. */
suggestion: SuggestionEntry;
}
interface SuggestionsDatabaseUpdateRemove {
/** Suggestion entry id. */
id: SuggestionId;
}
interface SuggestionsDatabaseUpdateModify {
/** Suggestion entry id. */
id: SuggestionId;
/** The new external id. */
externalId?: FieldUpdate<UUID>;
/** The list of argument updates. */
arguments?: SuggestionArgumentUpdate[];
/** The new module name. */
module?: FieldUpdate<string>;
/** The new self type. */
selfType?: FieldUpdate<string>;
/** The new return type. */
returnType?: FieldUpdate<string>;
/** The new documentation string. */
documentation?: FieldUpdate<string>;
/** The new scope. */
scope?: FieldUpdate<SuggestionEntryScope>;
/** The new reexport field. */
reexport?: FieldUpdate<string>;
}
SuggestionsOrderDatabaseUpdateThe update of the suggestions order database.
/** The kind of the suggestions order database update. */
type SuggestionsOrderDatabaseUpdate =
| SuggestionsOrderDatabaseUpdateAdd
| SuggestionsOrderDatabaseUpdateRemove
| SuggestionsOrderDatabaseUpdateModify;
interface SuggestionsOrderDatabaseUpdateAdd {
entry: SuggestionOrderDatabaseEntry;
}
interface SuggestionsOrderDatabaseUpdateRemove {
/** The unique identifier of a suggestion. */
suggestionId: SuggestionId;
}
interface SuggestionsOrderDatabaseUpdateModify {
/** The unique identifier of a suggestion. */
suggestionId: SuggestionId;
/** The previous suggestion id to update. */
prevId?: FieldUpdate<SuggestionId>;
/** The next suggestion id to update. */
nextId?: FieldUpdate<SuggestionId>;
}
ExportThe info about module re-export.
type Export = ExportQualified | ExportUnqualified;
interface ExportQualified {
/** The module that re-exports the given module. */
module: string;
/** The new name of the given module if it was renamed in the export clause.
*
* e.g. `X` in `export A.B as X`. */
alias?: string;
}
interface ExportUnqualified {
/** The module name that re-exports the given module. */
module: string;
}
FileA representation of a file on disk.
interface File {
/** Includes the file extension. */
name: string;
type: string;
}
DirectoryTreeA directory tree is a recursive type used to represent tree structures of files
and directories. It contains files and symlinks in the files section and
directories in the directories section. When the tree was requested with the
parameter limiting the maximum depth, the bottom of the DirectoryTree will
contain Directory node in the files section indicating that there is a
directory, but the contents are unknown because we've reached the maximum depth.
interface DirectoryTree {
path: Path;
name: string;
files: FileSystemObject[];
directories: DirectoryTree[];
}
FileAttributesA description of the attributes of a file required by the IDE. These attributes may be expanded in future.
/** A representation of the attributes of a file.
*
* @param creationTime creation time
* @param lastAccessTime last access time
* @param lastModifiedTime last modified time
* @param kind type of [[FileSystemObject]], can be: `Directory`, `File`, `Other`
* @param byteSize size in bytes */
interface FileAttributes {
creationTime: UTCDateTime;
lastAccessTime: UTCDateTime;
lastModifiedTime: UTCDateTime;
kind: FileSystemObject;
byteSize: number;
}
UTCDateTimeTime in UTC time zone represented as ISO-8601 string
type UTCDateTime = string;
FileEventKindThe kind of event being described for a watched file.
type FileEventKind = "Added" | "Removed" | "Modified";
PositionA representation of a position in a text file.
interface Position {
/** Line position in a document (zero-based). */
line: number;
/** Character offset on a line in a document (zero-based). Assuming that the
* line is represented as a string, the `character` value represents the gap
* between the `character` and `character + 1`.
*
* If the character value is greater than the line length it defaults back to
* the line length. */
character: number;
}
namespace org.enso.languageserver.protocol.binary;
struct Position {
// Line position in a document (zero-based)
line: uint64;
// Character offset on a line in a document (zero-based)
character: uint64;
}
RangeA representation of a range of text in a text file.
For example, given the function.
0|inc x =
1| x + 1
^^^^^^^^^
012345678
The range of inc is
{
start: { line: 0, character: 0},
end: { line: 0, character: 3}
}
The range of 1 is
{
start: { line: 1, character: 8},
end: { line: 1, character: 9}
}
For unicode characters, the range is measured in code units, for example given
the function with the old key emoji foo 🗝 = ... argument consisting of two
unicode code units \uD83D and \uDDDD.
0|foo \uD83D\uDDDD = ...
^^^^^^^^^^^^^^^^^^
01234 5 67
The range of old key emoji 🗝 argument is
{
start: { line: 0, character: 4},
end: { line: 0, character: 6}
}
interface Range {
/** The range's start position (inclusive). */
start: Position;
/** The range's end position (exclusive). */
end: Position;
}
TextEditA representation of a change to a text file at a given position.
interface TextEdit {
/** The range of text in a text file. */
range: Range;
/** The change to a text file. */
text: string;
}
DiagnosticTypeThe type of diagnostic message.
type DiagnosticType = "Error" | "Warning";
StackTraceElementThe frame of the stack trace. If the error refer to a builtin node, the path
and location fields will be empty.
interface StackTraceElement {
/** The function name containing the stack trace element. */
functionName: string;
/** The location of the file. */
path?: Path;
/** The location of the element in the file. */
location?: Range;
}
ExecutionResultAn execution result object is produced as a result of an execution attempt.
Compared to Diagnostic object it can also represent a critical failure
information.
DiagnosticA diagnostic object is produced as a result of an execution attempt, like
pushing the method pointer to a call stack, or editing the file. It can
represent a compiler warning, a compilation error, or a runtime error. The
message has optional path, location and stack fields containing
information about the location in the source code.
In case of the runtime errors, the path and location fields may be empty if
the error happens in a builtin node. Then, to locate the error in the code, you
can use the stack field with a stack trace to find the first element with
non-empty location (as the head of the stack will point to the builtin element).
interface Diagnostic {
/** The type of diagnostic message. */
kind: DiagnosticType;
/** The diagnostic message. */
message: string;
/** The location of the file containing the diagnostic. */
path?: Path;
/** The location of the diagnostic object in the file. */
location?: Range;
/** The id of the related expression. */
expressionId?: ExpressionId;
/** The stack trace. */
stack: StackTraceElement[];
}
SHA3-224The SHA3-224 message digest encoded as a base16 string. For the equivalent
structure on the binary connection please see EnsoDigest
type SHA3_224 = string;
FileEditA representation of a batch of edits to a file, versioned.
SHA3_224 represents hash of the file contents. oldVersion is the version
you're applying your update on, newVersion is what you compute as the hash
after applying the changes. In other words,
hash(origFile) == oldVersion
hash(applyEdits(origFile, edits)) == newVersion
it's a sanity check to make sure that the diffs are applied consistently.
Consecutive text edits are applied sequentially, every one acting on the result of applying previous ones on the original buffer contents. In pseudocode:
applyEdits buffer [] = buffer
applyEdits buffer (first : rest) = applyEdits (applyTextEdit buffer first) rest
interface FileEdit {
path: Path;
edits: TextEdit[];
oldVersion: SHA3_224;
newVersion: SHA3_224;
}
FileContentsA representation of the contents of a file.
interface FileContents<T> {
contents: T;
}
class TextFileContents extends FileContents<string> {}
FileSystemObjectA representation of what kind of type a filesystem object can be.
type FileSystemObject = Directory | SymlinkLoop | File | Other;
/**
* Represents a directory.
*
* @param name a name of the directory
* @param path a path to the directory
*/
interface Directory {
name: string;
path: Path;
}
/**
* Represents a symbolic link that creates a loop.
*
* @param name a name of the symlink
* @param path a path to the symlink
* @param target a target of the symlink. Since it is a loop,
* target is a subpath of the symlink
*/
interface SymlinkLoop {
name: string;
path: Path;
target: Path;
}
/**
* Represents a file.
*
* @param name a name of the file
* @param path a path to the file
*/
interface File {
name: string;
path: Path;
}
/**
* Represents unrecognized object.
* Example is a broken symbolic link.
*/
interface Other {
name: string;
path: Path;
}
WorkspaceEditThis is a message to be specified once we better understand the intricacies of undo/redo.
The actionables for this section are:
- Work out the design of this message.
- Specify this message.
EnsoDigestA counterpart to SHA3-224 for the binary connection, this is a standard message digest encoded using FlatBuffers.
namespace org.enso.languageserver.protocol.binary;
table EnsoDigest {
bytes : [ubyte] (required);
}
Notes:
bytes to not be equal to 28 (224
/ 8). This is the length of the chosen digest in bytes.FileSegmentA representation of a segment of a file for use in the binary protocol.
namespace org.enso.languageserver.protocol.binary;
table FileSegment {
// The file to access.
path : Path (required);
// The byte offset in the file to read from.
byteOffset : ulong;
// The number of bytes to read.
length : ulong;
}
The byteOffset property is zero-indexed, so the last byte in the file is at
index file.length - 1.
ContentRootA representation of a content root for use in the IDE. A content root represents a location on a real file-system that has been virtualised for use in the Enso VFS.
type ContentRoot = Project | FileSystemRoot | Home | Library | Custom;
/** This content root points to the project home. */
interface Project {
/** A unique identifier for the content root. */
id: UUID;
}
/** This content root points to the system root (`/`) on unix systems, or to a
* drive root on Windows. In Windows' case, there may be multiple `Root` entries
* corresponding to the various drives. */
interface FileSystemRoot {
/** A unique identifier for the content root. */
id: UUID;
/** The absolute filesystem path of the content root. */
path: string;
}
/** The user's home directory. */
interface Home {
/** A unique identifier for the content root. */
id: UUID;
}
/** An Enso library location. */
interface Library {
/** A unique identifier for the content root. */
id: UUID;
/** The namespace of the library. */
namespace: string;
/** The name of the library. */
name: string;
/** The version of the library.
* It is either a semver version or the string "local". */
version: string;
}
/** A content root that has been added by the IDE (unused for now). */
interface Custom {
/** A unique identifier for the content root. */
id: UUID;
}
LibraryEntryRepresents a library available in a resolved edition.
interface LibraryEntry {
namespace: string;
name: string;
version: LibraryVersion;
isCached: boolean;
}
LibraryVersionRepresents a library version, as returned in LibraryEntry.
type LibraryVersion = LocalLibraryVersion | PublishedLibraryVersion;
/** A library version that references a version of the library published in some
* repository. */
interface PublishedLibraryVersion {
/** A semver-compliant version of the library. */
version: string;
/** A URL to the repository from which this library will be downloaded. */
repositoryUrl: string;
}
/** A library version that references a locally editable version of the library.
*/
interface LocalLibraryVersion {}
ContactRepresents contact information of authors or maintainers.
Both fields are optional, but for the contact to be valid, at least one of them must be defined.
interface Contact {
name?: string;
email?: string;
}
EditionReferenceA reference to a specific edition.
Currently, it can either reference an edition by its name, or reference the edition associated with the currently open project.
type EditionReference = NamedEdition | CurrentProjectEdition;
/** The edition associated with the current project, with all of its overrides.
*/
interface CurrentProjectEdition {}
/** An edition stored under a given name. */
interface NamedEdition {
editionName: string;
}
LibraryComponentGroupsThe description of component groups provided by the package. Object fields can be omitted if the corresponding list is empty.
interface LibraryComponentGroups {
/** The list of component groups provided by the package. */
newGroups?: LibraryComponentGroup[];
/** The list of component groups that this package extends.*/
extendedGroups?: LibraryComponentGroup[];
}
LibraryComponentGroupThe component group provided by a library.
interface LibraryComponentGroup {
/** The fully qualified library name. A string consisting of a namespace and
* a library name separated by a dot `<namespace>.<library name>`,
* e.g. `Standard.Base`. */
library: string;
/** The group name without the library name prefix.
* e.g. given the `Standard.Base.Group 1` group reference,
* the `name` field contains `Group 1`. */
name: string;
color?: string;
icon?: string;
/** A list of components provided by this component group. */
exports: LibraryComponent[];
}
LibraryComponentA single component of a component group.
interface LibraryComponent {
/** The component name. */
name: string;
/** The component shortcut. */
shortcut?: string;
}
In order to properly set-up and tear-down the language server connection, we need a set of messages to control this process.
session/initProtocolConnectionThis message initializes the connection used to send the textual protocol messages. This initialization is important such that the client identifier can be correlated between the textual and data connections.
The subsequent session/initProtocolConnection calls with same clientId will
immediately return success message.
interface SessionInitProtocolConnectionParameters {
clientId: UUID;
}
interface SessionInitProtocolConnectionResult {
contentRoots: ContentRoot[];
}
SessionAlreadyInitialisedError to signal
that the session is already initialized with different clientId.ResourcesInitializationError to signal
about the error during the initialization of Language Server resources.session/initBinaryConnectionThis message initializes the data connection used for transferring binary data between engine and clients. This initialization is important such that the client identifier can be correlated between the data and textual connections.
namespace org.enso.languageserver.protocol.binary;
// A command initializing a data session.
table InitSessionCommand {
// A unique identifier of a client initializing the session.
identifier: EnsoUUID (required);
}
root_type InitSessionCommand;
namespace org.enso.languageserver.protocol.binary;
// Indicates an operation has succeeded.
table Success {}
None
In order to mediate between multiple clients properly, the language server has a robust notion of capability management to grant and remove permissions from clients.
capability/acquireThis requests that the server grant the specified capability to the requesting client.
interface CapabilityAcquireParameters {
method: string;
registerOptions?: any;
}
The registerOptions are determined by the method. The method must be listed
in the section on capabilities below.
type CapabilityAcquireResult = null;
TBC
capability/releaseThis requests that the server acknowledge that the client is releasing a given capability.
interface CapabilityReleaseParameters {
registration: CapabilityRegistration;
}
type CapabilityReleaseResult = null;
TBC
capability/grantedThis notifies the client that it has been granted a capability without any action on its part.
interface CapabilityGrantedNotification {
registration: CapabilityRegistration;
}
capability/forceReleasedThis notifies the client that a capability has been forcibly removed from its capability set.
interface CapabilityForceReleasedNotification {
registration: CapabilityRegistration;
}
TBC
The capability management features work with the following capabilities.
text/canEditThis capability states that the capability has the ability to perform both
text/applyEdit and text/save for the specified file.
text/canEdit{path: Path;}None
file/receivesTreeUpdatesThis capability states that the client will receive updates for any watched content roots in the current project.
file/receivesTreeUpdates{ path: Path; }None
FileSystemError to signal a generic, unrecoverable
file-system error.FileNotFound informs that path cannot be found.CapabilityNotAcquired informs that requested
capability is not acquired.executionContext/canModifyThis capability states that the client has the ability to modify an execution context, including modifying the execution stack, invalidating caches, or destroying the context.
executionContext/canModify{ contextId: ContextId; }executionContext/destroyexecutionContext/recomputeexecutionContext/interruptexecutionContext/pushexecutionContext/popexecutionContext/executeExpressionexecutionContext/attachVisualizationexecutionContext/modifyVisualizationexecutionContext/detachVisualizationexecutionContext/visualizationUpdateexecutionContext/visualizationEvaluationFailedNone
executionContext/receivesUpdatesThis capability states that the client receives expression value updates from a given execution context.
executionContext/receivesUpdates{ contextId: ContextId; }executionContext/expressionUpdatesexecutionContext/executionFailedexecutionContext/executionStatusNone
search/receivesSuggestionsDatabaseUpdatesThis capability states that the client receives the search database updates for a given execution context.
search/receivesSuggestionsDatabaseUpdates{}None
The language server also provides file operations to the IDE.
file/writeThis requests that the file manager component write to a specified file with the specified contents.
This request is explicitly allowed to write to files that do not exist, and will create them under such circumstances. If a file is recorded as 'open' by one of the clients, and another client attempts to write to that file, the write must fail.
interface FileWriteParameters {
path: Path;
contents: FileContents<T>;
}
type FileWriteResult = null;
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.file/readThis requests that the file manager component reads the contents of a specified file.
If the file is recorded as open by the language server, then the result will return the contents from the in-memory buffer rather than the file on disk.
interface FileReadParameters {
path: Path;
}
interface FileReadResult {
contents: FileContents<T>;
}
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.FileNotFound informs that file cannot be found.file/writeBinaryThis requests that the file manager component write to a specified file with the binary contents.
This request is explicitly allowed to write to files that do not exist, and will create them under such circumstances. If a file is recorded as 'open' by one of the clients, and another client attempts to write to that file, the write must fail.
namespace org.enso.languageserver.protocol.binary;
// A command writing binary contents to a file.
table WriteFileCommand {
// A path to a file.
path: Path;
// Binary contents.
contents: [ubyte];
}
namespace org.enso.languageserver.protocol.binary;
// Indicates an operation has succeeded.
table Success {}
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.file/readBinaryThis requests that the file manager component reads the binary contents of a specified file.
If the file is recorded as open by the language server, then the result will return the contents from the in-memory buffer rather than the file on disk.
namespace org.enso.languageserver.protocol.binary;
// A command reading binary contents from a file.
table ReadFileCommand {
// A path to a file.
path: Path;
}
namespace org.enso.languageserver.protocol.binary;
// A reply for a ReadFileCommand.
table FileContentsReply {
// Binary contents.
contents: [ubyte];
}
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.FileNotFound informs that file cannot be found.file/writeBytesThis requests that the file manager component writes a set of bytes to the specified file at the specified offset.
This method will create a file if no file is present at path.
overwriteExisting boolean should be set if byteOffset is less than the
length of the file.byteOffset property is zero-indexed. To append to the file you begin
writing at index file.length.byteOffset is less than the length of the file and overwriteExisting is
set, it will truncate the file to length byteOffset + bytes.length.byteOffset > file.length, the bytes in the range
[file.length, byteOffset) will be filled with null bytes. Please note that,
in this case, the checksum in the response will also be calculated on the null
bytes.namespace org.enso.languageserver.protocol.binary;
table WriteBytesCommand {
// The file to write to.
path: Path (required);
// The byte offset in the file to write from.
byteOffset: ulong;
// Whether existing content should be overwritten.
overwriteExisting: bool;
// The file contents.
bytes: [ubyte] (required);
}
namespace org.enso.languageserver.protocol.binary;
table WriteBytesReply {
// The checksum of the written bytes.
checksum: EnsoDigest (required);
}
Notes:
checksum is only of the bytes in the request as they were written to
disk. This does not include checksumming the entire file. For that, please
see file/checksumBytes.CannotOverwrite to signal that an overwrite would be
necessary to perform the operation but that overwriteExisting is not set.NotFile if the provided segment.path is not a file.file/readBytesAsks the language server to read the specified number of bytes at the specified offset in the file.
It will attempt to read as many as segment.length bytes, but does not
guarantee that the response will contain segment.length bytes (e.g. if
segment.length would require reading off the end of the file).
namespace org.enso.languageserver.protocol.binary;
table ReadBytesCommand {
// The segment in a file to read bytes from.
segment: FileSegment (required);
}
namespace org.enso.languageserver.protocol.binary;
table ReadBytesReply {
// The checksum of the bytes in this response.
checksum: EnsoDigest (required);
// The requested file contents.
bytes: [ubyte] (required);
}
Notes:
checksum is of the bytes as they have been read from disk.FileNotFound if the file at segment.path does not exist.ReadOutOfBounds if segment.byteOffset is not present
in the file at segment.path.NotFile if the provided segment.path is not a file.file/createThis request asks the file manager to create the specified file system object.
This will fail if the specified object already exists.
interface FileCreateParameters {
object: FileSystemObject;
}
type FileCreateResult = null;
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.file/deleteThis request asks the file manager to delete the specified file system object.
interface FileCreateParameters {
path: Path;
}
type FileDeleteResult = null;
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that file cannot be found.FileExists informs that file already existsfile/copyThis request asks the file manager to copy a specified filesystem object to another location.
interface FileCopyParameters {
from: Path;
to: Path;
}
type FileCopyResult = null;
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that file cannot be found.file/moveThis request asks the file manager to move a specified filesystem object to another location.
The move should be specified by filesystem events, and such notifications should inform the client that the currently edited file has been moved.
interface FileMoveParameters {
from: Path;
to: Path;
}
type FileMoveResult = null;
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that file cannot be found.FileExists informs that target file already exists.file/existsThis request asks the file manager to check whether a filesystem object exists at the specified path.
interface FileExistsParameters {
path: Path;
}
interface FileExistsResult {
exists: boolean;
}
ContentRootNotFoundError to signal that the
requested content root cannot be found.file/treeThis request asks the file manager component to generate and provide the directory tree starting at a given path.
interface FileTreeParameters {
path: Path;
depth?: number;
}
interface FileTreeResult {
tree: DirectoryTree;
}
ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that requested path does not exist or
provided depth argument is <= 0.NotDirectory informs that requested path is not a
directory.file/listThis request lists the contents of a given filesystem object. For a file it will just return the file, while for a directory it will list the contents of the directory.
interface FileListParameters {
path: Path;
}
interface FileListResult {
paths: FileSystemObject[];
}
ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that requested path does not exist.NotDirectory informs that requested path is not a
directory.file/infoThis request gets information about a specified filesystem object.
This request should work for all kinds of filesystem object.
interface FileInfoParameters {
path: Path;
}
interface FileInfoResult {
attributes: FileAttributes;
}
ContentRootNotFoundError to signal that the
requested content root cannot be found.FileNotFound informs that requested path does not exist.file/checksumRequests that the language server provide the checksum of the provided file.
Only defined when the provided path is a file.
It calculates the checksum of the entire file.
interface ChecksumRequest {
/** The path to the file to get the checksum for. */
path: Path;
}
interface ChecksumResponse {
/** The checksum of the file at `path`. */
checksum: SHA3_224;
}
FileNotFound if the file at path does not exist.NotFile if the provided path does not point to a file.file/checksumBytesRequests that the language server provides the checksum of the provided byte range.
namespace org.enso.languageserver.protocol.binary;
table ChecksumBytesCommand {
// The segment in a file to checksum.
segment : FileSegment (required);
}
namespace org.enso.languageserver.protocol.binary;
table ChecksumBytesReply {
// The segment in a file to checksum.
checksum : EnsoDigest;
}
FileNotFound if the file at segment.path does not exist.ReadOutOfBounds if segment.byteOffset is not present
in the file at segment.path, or if segment.length does not fit within the
file.NotFile if the provided segment.path is not a file.file/eventThis is a notification that is sent every time something under a watched content root changes. It is used to ensure that the client's filesystem representation stays in synchronisation with reality.
Events should be sent from server to client for every event observed under one of the (possibly multiple) content roots.
interface FileEventNotification {
path: Path;
kind: FileEventKind;
attributes?: FileAttributes;
}
file/rootAddedThis is a notification sent to all clients to inform them that a content root has been added.
At the beginning, a series of notifications is sent that lists all content roots
that are present at the current moment. This message may contain the same
content roots that were already present in the session/initProtocolConnection.
That is done, because there is no guarantee that no root has been added between
the init message and the time when notifications start being sent, and this
ensures that no content root is missed.
interface FileRootAddedNotification {
root: ContentRoot;
}
file/rootRemovedThis is a notification sent to all clients other than the one performing the removal of the content root in order to inform them of the removal of the root.
interface FileRootRemovedNotification {
/** The ID of the content root. */
id: UUID;
}
The language server has a set of version control operations to keep track of changes made to the projects.
vcs/initThis requests that the VCS manager component initializes version control for the project identified by the root directory.
This request assumes that no prior VCS is present for the project at a specified location. If VCS has already been initialized once, the operation will fail.
interface VCSInitParameters {
root: Path;
}
type VCSInitResult = null;
VCSError to signal a generic, unrecoverable VCS error.ProjectNotFound to signal that the requested
project does not existVCSAlreadyPresent to signal that the requested
project does not existvcs/saveThis requests that the VCS manager component record any changes made to the project, compared to the last save.
This request assumes that the project at a specified location exists and VCS has
been initialized for it with vcs/init operation. If the project is not under
Enso's version control system, the operation must fail. If no changes have been
recorded since the last save, the operation must still succeed. All saves
include a timestamp when the request was made. For easier identification, the
request has an optional name parameter that will prefix the timestamp.
interface VCSSaveParameters {
root: Path;
name?: string;
}
interface VCSSaveResult {
commitId: string;
message: string;
}
VCSError to signal a generic, unrecoverable VCS error.ProjectNotFound to signal that the requested
project does not existVCSNotFound to signal that the project is not under
Enso's version controlvcs/statusThis requests that the VCS manager component report the current status of the changes made to the project.
This request assumes that the project at a specified location exists and VCS has
been initialized for it with vcs/init operation. If the project is not under
Enso's version control system, the operation must fail. The status of the
project includes:
dirtty flag, indicating if any of the project files has been modified, added
or deletedinterface VCSStatusParameters {
root: Path;
}
interface VCSStatusResult {
dirty: boolean;
changed: Path[];
lastSave: {
commitId: string;
message: string;
};
}
VCSError to signal a generic, unrecoverable VCS error.ProjectNotFound to signal that the requested
project does not existVCSNotFound to signal that the project is not under
Enso's version controlvcs/restoreThis requests that the VCS manager component restores the project to a past state recorded in Enso's VCS. All unsaved changes will be lost.
This request assumes that the project at a specified location exists and VCS has
been initialized for it with vcs/init operation. If the project is not under
Enso's version control system, the operation must fail.
The request has an optional commitId parameter that refers to the past
checkpoint recorded with vcs/save. If no save exists with a provided
commitId, the request must fail. If no commitId exists, the operation will
restore the project to the last saved state, will all current modifications
forgotten.
If the contents of any open buffer has changed as a result of this operation,
all subscribed clients will be notified about the new version of the file via
text/didChange push notification.
A file might have been removed during the operation while there were still open
buffers for that file. Any such clients will be modified of a file removal via
the file/event notification.
The result of the call returns a list of files that have been modified during the operation.
interface VCSRestoreParameters {
root: Path;
commitId?: string;
}
interface VCSRestoreResult {
changed: Path[];
}
VCSError to signal a generic, unrecoverable VCS error.ProjectNotFound to signal that the requested
project does not existVCSNotFound to signal that the project is not under
Enso's version controlSaveNotFound to signat that the requested save could
not be identified in the project's version controlvcs/listThis requests that the VCS manager component returns a list of project's saves.
By default, the operation will return all project's saves. An optional limit
parameter will ensure that only the last limti ones are reported.
This request assumes that the project at a specified location exists and VCS has
been initialized for it with vcs/init operation. If the project is not under
Enso's version control system, the operation must fail.
interface VCSListParameters {
root: Path;
limit?: number;
}
interface VCSListResult {
saves: [
{
commitId: string;
message: string;
},
];
}
VCSError to signal a generic, unrecoverable VCS error.ProjectNotFound to signal that the requested
project does not existVCSNotFound to signal that the project is not under
Enso's version controlThe language server also has a set of text editing operations to ensure that it stays in sync with the clients.
text/openFileThis requests the language server to open the specified file.
If no client has write lock on the opened file, the capability is granted to the
client that sent the text/openFile message.
interface TextOpenFileParameters {
path: Path;
}
interface TextOpenFileResult {
writeCapability?: CapabilityRegistration;
content: string;
currentVersion: SHA3_224;
}
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.FileNotFound informs that file cannot be found.text/openBufferThis requests the language server to open a specified in-memory buffer mapped to
the provided path. If the path exists, this command behaves the same as
text/openFile. If the path does not exist, the command
creates empty in-memory buffer for the provided path.
If no client has write lock on the opened file, the capability is granted to the
client that sent the text/openBuffer message. The in-memory buffers can be
used to define hidden modules with visualization functions. In a nutshell, the
request behaves the same as text/openFile but does not
require the file to exist.
interface TextOpenBufferParameters {
path: Path;
}
interface TextOpenBufferResult {
writeCapability?: CapabilityRegistration;
content: string;
currentVersion: SHA3_224;
}
FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that a user doesn't have
access to a resource.text/closeFileThis requests the language server to close the specified file.
Any pending changes to files will be saved before closing the file.
interface TextCloseFileParameters {
path: Path;
}
type TextOpenFileResult = null;
FileNotOpenedError to signal that a file wasn't
opened.text/saveThis requests for the language server to save the specified file.
The request may fail if the requesting client does not have permission to edit that file, or if the client is requesting a save of an outdated version. Note that language-server autosaves changes to the file, making this operation obsolete.
interface TextSaveParameters {
path: Path;
currentVersion: SHA3 - 224;
}
type TextSaveResult = null;
FileNotOpenedError to signal that the file isn't
open.InvalidVersionError to signal that the version
provided by the client doesn't match the version computed by the server.WriteDeniedError to signal that the client doesn't hold
write lock for the buffer.FileSystemError to signal a generic, unrecoverable
file-system error.ContentRootNotFoundError to signal that the
requested content root cannot be found.AccessDeniedError to signal that the user doesn't have
access to a resource.text/applyEditThis requests that the server apply a series of edits to the project. These edits solely concern text files.
This operation may fail if the requesting client does not have permission to edit the resources for which edits are sent. This failure may be partial, in that some edits are applied and others are not.
interface TextApplyEditParameters {
/** The file edit. */
edit: FileEdit;
/**
* A flag indicating whether we should re-execute the program after applying
* the edit. Default value is `true`, indicating the program should be
* re-executed.
*/
execute?: boolean;
/**
* An identifiers map associated with this file as an array of
* index, length, uuid triples. The old id map format that was used in the
* source file is also supported.
*/
idMap?: [number, number, UUID][];
}
type TextApplyEditResult = null;
FileNotOpenedError to signal that the file isn't
open.TextEditValidationError to signal that
validation has failed for a series of edits.InvalidVersionError to signal that the version
provided by the client doesn't match the version computed by the server.WriteDeniedError to signal that the client doesn't hold
write lock for the buffer.text/applyExpressionValueThis requests to set an expression to a new value. For example, it can update a
literal value, like changing 98 to 99, true to false or "Hello" to
"World!". This method is a more specific version of
text/applyEdit and guarantees that the syntax tree is not
changed after applying the edit. This way the engine can perform a more
efficient value swap instead of reparsing and recompiling the whole module.
This operation may fail if the requesting client does not have permission to edit the resources for which edits are sent.
interface TextApplyExpressionValueParameters {
/** The expression id to update. */
expressionId: ExpressionId;
/** The path to the file. */
path: Path;
/** The file edit containing the new expression value. */
edit: TextEdit;
/** The current version of the buffer. */
oldVersion: SHA3_224;
/** The version of the buffer after applying the edit. */
newVersion: SHA3_224;
}
type TextApplyExpressionValueResult = null;
FileNotOpenedError to signal that the file isn't
open.TextEditValidationError to signal that
validation has failed for this edit.InvalidVersionError to signal that the version
provided by the client doesn't match the version computed by the server.WriteDeniedError to signal that the client doesn't hold
write lock for the buffer.text/didChangeThis is a notification sent from the server to the clients to inform them of any changes made to files that they have open.
This notification must only be sent for files that the client has open.
interface TextDidChangeNotification {
edits: FileEdit[];
}
text/autoSaveThis is a notification sent from the server to the clients to inform them of any successful auto-save action.
This notification must only be sent for files that the client has open.
interface TextAutoSaveNotification {
path: Path;
}
text/fileModifiedOnDiskThis is a notification sent from the server to the clients to inform them that the file was modified on disk by an external editor.
interface TextFileModifiedOnDiskNotification {
path: Path;
}
The language server also has a set of operations useful for managing the client workspace.
workspace/projectInfoThis request allows the IDE to request information about the currently open project in situations where it does not have a project manager to connect to.
interface WorkspaceProjectInfoParameters {}
interface WorkspaceProjectInfoResult {
/** The name of the project. */
projectName: string;
/** The engine version on which the project is running. */
engineVersion: string;
/** The version of graal on which the project is running. */
graalVersion: string;
}
CannotDecode if the project configuration cannot be
decoded.FileNotFound if the project configuration cannot be found.The language server also has a heartbeat operation to monitor the Language server. This API is private and should be used only by the Project Manager.
heartbeat/pingThis request is sent from the supervisor process to the server to check the health of the Language Server.
interface HeartbeatPingParameters {}
type HeartbeatPingResult = null;
None
heartbeat/initThis request is sent from the bootloader to check if the started language server instance has finished initialization. A reply should only be sent when the main module has been fully initialized.
interface HeartbeatInitParameters {}
type HeartbeatInitResult = null;
None
The language server also provides refactoring operations to restructure an internal body of code.
refactoring/renameProjectThis request is sent from the project manager to the server to refactor project name in an interpreter runtime.
interface RefactoringRenameProjectParameters {
namespace: string;
oldName: string;
newName: string;
}
type RefactoringRenameProjectResult = null;
ProjectRenameFailed to signal that the project
rename operation has failed.refactoring/renameSymbolSent from the client to the server to rename a symbol in the program. The text
edits required to perform the refactoring will be returned as a
text/didChange notification.
Refactorins supports only limited cases listed below.
main =
operator1 = 42
^^^^^^^^^
Expression id in the request should point to the left hand side symbol of the assignment.
function1 x = x
^^^^^^^^^
main =
operator1 = Main.function1 42
Expression id in the request should point to the symbol defining the function.
Current limitations of the method renaming are:
Main.function1 x = x
interface RefactoringRenameSymbolParameters {
/** The qualified module name. */
module: string;
/** The symbol to rename. */
expressionId: ExpressionId;
/** The new name of the symbol. If the provided name is not a valid Enso
* identifier (contains unsupported symbols, spaces, etc.), it will be normalized.
* The final name will be returned in the response. */
newName: string;
}
interface RefactoringRenameSymbolResult {
newName: string;
}
ModuleNotFoundError to signal that the requested
module cannot be found.ExpressionNotFoundError to signal that the given
expression cannot be found.FailedToApplyEdits to signal that the refactoring
operation was not able to apply generated edits.RefactoringNotSupported to signal that the
refactoring of the given expression is not supported.DefinitionAlreadyExists to signal that the
definition with the provided name already exists in scope.refactoring/projectRenamedThis is a notification sent from the server to the clients to inform them about the new project name.
interface RefactoringProjectRenamedNotification {
/** Old normalized name of the project. */
oldNormalizedName: string;
/** New normalized name of the prject. */
newNormalizedName: string;
/** New display name of the project. */
newName: string;
}
The execution management portion of the language server API deals with exposing fine-grained control over program and expression execution to the clients of the language server. This is incredibly important for enabling the high levels of interactivity required by Enso Studio.
Given the default project structure.
├── package.yaml
└── src
└── Main.enso
$ cat src/Main.enso
main =
x = 6
y = x.foo 5
z = y + 5
z
Number.foo = x ->
y = this + 3
z = y * x
z
#### METADATA ####
[[{"index": {"value": 98}, "size": {"value": 5}}, "5fc0c11d-bd83-4ca3-b847-b8e362f7658c"],[{"index": {"value": 81}, "size": {"value": 8}}, "1cda3676-bd62-41f8-b6a1-a1e1b7c73d18"],[{"index": {"value": 42}, "size": {"value": 5}}, "899a11e5-4d2b-43dc-a867-2f2ef2d2ba62"],[{"index": {"value": 26}, "size": {"value": 7}}, "37f284d4-c593-4e65-a4be-4948fbd2adfb"],[{"index": {"value": 16}, "size": {"value": 1}}, "c553533e-a2b9-4305-9f12-b8fe7781f933"]]
[]
Notice extra newline in the beginning of the Main.enso file, it is important
for the precalculated metadata indexes.
{
"jsonrpc": "2.0",
"method": "executionContext/create",
"id": 0,
"params": null
}
Return capabilities together with a newly created ContextId.
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3",
"canModify": {
"method": "executionContext/canModify",
"registerOptions": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3"
}
},
"receivesUpdates": {
"method": "executionContext/receivesUpdates",
"registerOptions": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3"
}
}
}
}
Entering the main method. First item on the stack should always be an
ExplicitCall.
{
"jsonrpc": "2.0",
"method": "executionContext/push",
"id": 0,
"params": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3",
"stackItem": {
"type": "ExplicitCall",
"methodPointer": {
"file": {
"rootId": "18f642a2-5f69-4fc8-add6-13bf199ca326",
"segments": ["src", "Main.enso"]
},
"definedOnType": "Main",
"name": "main"
},
"thisArgumentExpression": null,
"positionalArgumentsExpressions": []
}
}
}
Returns successful reponse.
{
"jsonrpc": "2.0",
"id": 0,
"result": null
}
And a value update, result of the method foo call defined on type Number.
{
"jsonrpc": "2.0",
"method": "executionContext/expressionValuesComputed",
"params": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3",
"updates": [
{
"id": "37f284d4-c593-4e65-a4be-4948fbd2adfb",
"type": "Number",
"shortValue": "45",
"methodCall": {
"file": {
"rootId": "18f642a2-5f69-4fc8-add6-13bf199ca326",
"segments": ["src", "Main.enso"]
},
"definedOnType": "Number",
"name": "foo"
}
}
]
}
}
We can go deeper and evaluate the method foo call by pushing the LocalCall
on the stack. In general, all consequent stack items should be LocalCalls.
{
"jsonrpc": "2.0",
"method": "executionContext/push",
"id": 0,
"params": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3",
"stackItem": {
"type": "LocalCall",
"expressionId": "37f284d4-c593-4e65-a4be-4948fbd2adfb"
}
}
}
Returns successful response.
{
"jsonrpc": "2.0",
"id": 0,
"result": null
}
And update of some value inside the function foo.
{
"jsonrpc": "2.0",
"method": "executionContext/expressionValuesComputed",
"params": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3",
"updates": [
{
"id": "1cda3676-bd62-41f8-b6a1-a1e1b7c73d18",
"type": "Number",
"shortValue": "9",
"methodCall": null
}
]
}
}
{
"jsonrpc": "2.0",
"method": "executionContext/pop",
"id": 0,
"params": {
"contextId": "1eb5ad04-4094-4c1f-be54-e9d29ddf19a3"
}
}
Popping one item will return us into the main method. Second call will clear
the stack. Subsequent pop calls will result in an error indicating that the
stack is empty.
executionContext/createSent from the client to the server to create a new execution context. Return
capabilities executionContext/canModify and
executionContext/receivesUpdates. The
command takes optional contextId parameter with the id to create. The command
is idempotent and returns success if the context with provided id already
exists.
interface ExecutionContextCreateParameters {
contextId?: ContextId;
}
interface ExecutionContextCreateResult {
contextId: ContextId;
canModify: CapabilityRegistration;
receivesUpdates: CapabilityRegistration;
}
None
executionContext/destroySent from the client to the server destroy an execution context and free its resources.
interface ExecutionContextDestroyParameters {
contextId: ContextId;
}
type ExecutionContextDestroyResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.ContextNotFoundError when context can not be found
by provided id.executionContext/forkSent from the client to the server to duplicate an execution context, creating
an independent copy, containing all the data precomputed in the first one.
Return capabilities executionContext/canModify
and executionContext/receivesUpdates.
interface ExecutionContextForkParameters {
contextId: ContextId;
}
interface ExecutionContextForkResult {
contextId: ContextId;
canModify: CapabilityRegistration;
receivesUpdates: CapabilityRegistration;
}
No known errors.
executionContext/pushSent from the client to the server execute item and move the execution context to a new location deeper down the stack. If a stack item becomes invalid because of a text edit (e.g. the root function of the view was removed), it will stop executing. If the function reappears, execution should resume as normal.
interface ExecutionContextPushParameters {
contextId: ContextId;
stackItem: StackItem;
}
type ExecutionContextPushResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.StackItemNotFoundError when the request stack
item could not be found.InvalidStackItemError when pushing LocalCall on
top of the empty stack, or pushing ExplicitCall on top of non-empty stack.executionContext/popSent from the client to the server move the execution context up the stack, corresponding to the client clicking out of the current breadcrumb.
interface ExecutionContextPopParameters {
contextId: ContextId;
}
type ExecutionContextPopResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.EmptyStackError when the user tries to pop an empty
stack.executionContext/recomputeSent from the client to the server to force recomputation of current position. May include a list of expressions for which caches should be invalidated.
interface ExecutionContextRecomputeParameters {
/** The execution context identifier. */
contextId: ContextId;
/** The expressions that will be invalidated before the execution.
*
* Only the provided expression ids are invalidated excluding the dependencies.
*/
invalidatedExpressions?: "all" | ExpressionId[];
/** The execution environment that will be used in the execution. */
executionEnvironment?: ExecutionEnvironment;
/** The execution configurations for particular expressions.
*
* The provided expressions will be invalidated from the cache with the
* dependencies. The result of the execution will stay in the cache until the
* cache is invalidated by editing the node or other means.
*/
expressionConfigs?: ExpressionConfig[];
}
type ExecutionContextRecomputeResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.EmptyStackError when the user tries to recompute an
empty stack.executionContext/interruptSent from the client to the server to interrupt the program execution in the provided execution context.
interface ExecutionContextInterruptParameters {
contextId: ContextId;
}
type ExecutionContextInterruptResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.executionContext/setExecutionEnvironmentSent from the client to the server to set the execution context environment. After setting the environment, the runtime interrupts the current execution, clears the caches, and schedules execution of the context.
interface ExecutionContextSetExecutionEnvironmentParameters {
contextId: ContextId;
executionEnvironment: ExecutionEnvironment;
}
type ExecutionContextSetExecutionEnvironmentResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.executionContext/getComponentGroupsSent from the client to the server to get the list of component groups available in runtime.
The request is deprecated in favor of
runtime/getComponentGroups.
interface ExecutionContextGetComponentGroupsParameters {
contextId: ContextId;
}
interface ExecutionContextGetComponentGroupsResult {
componentGroups: LibraryComponentGroup[];
}
AccessDeniedError when context with the provided id
does not exist.executionContext/expressionUpdatesSent from the server to the client to inform about new information for certain
expressions becoming available. Supersedes the
executionContext/expressionValuesComputed notification, that will be removed
in future versions.
interface ExecutionContextExpressionUpdatesNotification {
contextId: ContextId;
updates: ExpressionUpdate[];
}
executionContext/executionFailedSent from the server to the client to inform about a failure when attempting to execute a context.
The executionContext/executionStatus
notifies about potential problems in the code found by compiler which did not
prevent the execution from completing successfully. This message signals about
the non-critical errors during runtime, or critical failures in the logic or the
implementation. A critical failure can be a compiler crash, an attempt to
execute an empty stack, an error location a method or a module when issuing a
executionContext/push command.
executionContext/executionFailed and
executionContext/executionComplete
messages are mutually exclusive, indicating a failed or a successful execution,
respectively.
interface ExecutionContextExecutionFailedNotification {
/** The identifier of the execution context. */
contextId: ContextId;
/** The details of the failed execution. */
result: ExecutionResult;
}
executionContext/executionCompleteSent from the server to the client to inform about the successful execution of a context.
executionContext/executionFailed and
executionContext/executionComplete
messages are mutually exclusive, indicating a failed or a successful execution,
respectively.
interface ExecutionContextExecutionFailedNotification {
/** The identifier of the execution context. */
contextId: ContextId;
}
executionContext/executionStatusSent from the server to the client to inform about a status of execution.
interface ExecutionContextExecutionStatusNotification {
/** The identifier of the execution context. */
contextId: ContextId;
/** The list of encountered problems. */
diagnostics: Diagnostic[];
}
executionContext/executeExpressionThis message allows the client to execute an arbitrary expression in a context
of a given node. It behaves like putting a breakpoint after the expression with
expressionId and executing the provided expression. All the local and global
symbols that are available for the expressionId will be available when
executing the expression. The result of the evaluation will be delivered as a
visualization result on a binary connection. You can think of it as a oneshot
executionContext/attachVisualization
visualization request, meaning that the expression will be executed once.
For example, given the current code:
main =
operator1 = 42
operator2 = operator1 + 1
fun1 x = x.to_text
You can execute an expression in the context of a function body. In this case,
the expressionId should point to the body of a function. E.g. in the context
of main available symbols are operator1, operator2 and fun1.
Execute expression in the context of a local binding. E.g. in the context of
operator2 = operator1 + 1 available symbols are operator1, operator2 and
fun1.
Execute expression in the context of arbitrary expression. E.g. in the context
of operator1 + 1 available symbols are operator1 and fun1.
Type: Request
Direction: Client -> Server
Connection: Protocol
Visibility: Public
interface ExecutionContextExecuteExpressionParameters {
executionContextId: UUID;
visualizationId: UUID;
expressionId: UUID;
expression: string;
}
type ExecutionContextExecuteExpressionResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.ContextNotFoundError when context can not be found
by provided id.VisualizationExpressionError to signal that
the provided expression cannot be evaluated.executionContext/attachVisualizationThis message allows the client to attach a visualization, potentially preprocessed by some arbitrary Enso code, to a given node in the program.
interface ExecutionContextAttachVisualizationParameters {
visualizationId: UUID;
expressionId: UUID;
visualizationConfig: VisualizationConfiguration;
}
type ExecutionContextAttachVisualizationResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.ContextNotFoundError when context can not be found
by provided id.ModuleNotFoundError to signal that the module with
the visualization cannot be found.VisualizationExpressionError to signal that
the expression specified in the VisualizationConfiguration cannot be
evaluated.executionContext/detachVisualizationThis message allows a client to detach a visualization from the executing code.
interface ExecutionContextDetachVisualizationParameters {
executionContextId: UUID;
visualizationId: UUID;
expressionId: UUID;
}
type ExecutionContextDetachVisualizationResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.ContextNotFoundError when context can not be found
by provided id.VisualizationNotFoundError when a
visualization can not be found.executionContext/modifyVisualizationThis message allows a client to modify the configuration for an existing visualization.
A successful response means that the new visualization configuration has been applied. In case of an error response, the visualization state does not change.
interface ExecutionContextModifyVisualizationParameters {
visualizationId: UUID;
visualizationConfig: VisualizationConfiguration;
}
type ExecutionContextModifyVisualizationResult = null;
AccessDeniedError when the user does not hold the
executionContext/canModify capability for this context.ContextNotFoundError when context can not be found
by provided id.ModuleNotFoundError to signal that the module with
the visualization cannot be found.VisualizationExpressionError to signal that
the expression specified in the VisualizationConfiguration cannot be
evaluated.VisualizationNotFoundError when a
visualization can not be found.executionContext/visualizationUpdateThis message is responsible for providing a visualization data update to the client.
The visualizationData component of the table definition must be
pre-serialized before being inserted into this message. As far as this level of
transport is concerned, it is just a binary blob.
namespace org.enso.languageserver.protocol.binary;
// A visualization context identifying a concrete visualization.
table VisualizationContext {
// A visualization identifier.
visualizationId: EnsoUUID (required);
// A context identifier.
contextId: EnsoUUID (required);
// An expression identifier.
expressionId: EnsoUUID (required);
}
// An event signaling visualization update.
table VisualizationUpdate {
// A visualization context identifying a concrete visualization.
visualizationContext: VisualizationContext (required);
// A visualization data.
data: [ubyte] (required);
}
root_type VisualizationUpdate;
None
executionContext/visualizationEvaluationFailedSignals that an evaluation of a visualization expression on the computed value has failed.
interface ExecutionContextVisualizationEvaluationFailedNotification {
/** An execution context identifier. */
contextId: ContextId;
/** A visualization identifier. */
visualizationId: UUID;
/** An identifier of a visualised expression. */
expressionId: UUID;
/** An error message. */
message: string;
/** Detailed information about the error. */
diagnostic?: Diagnostic;
}
Search operations allow requesting for the autocomplete suggestions and search
for the documentation. Search operations return links to the items in the
Suggestions Database instead of returning full entries. Suggestions Database is
a key-value storage with SuggestionEntry values.
The following code snippet shows examples of the database entries.
type MyType a b
type Maybe
Nothing
Just a
is_just = case this of
Just _ -> true
Nothing -> false
foo x =
10 - x
Number.baz x =
this + x * 10
main =
x = foo 42
y = x.baz x
IO.println y
<Constructor>{
name: "MyType",
arguments: [],
returnType: "MyType",
};
<Constructor>{
name: "Nothing",
arguments: [],
returnType: "Maybe",
};
<Constructor>{
name: "Just",
arguments: [
{
name: "a",
type: "Any",
isSuspended: false,
hasDefault: false,
},
],
returnType: "Maybe",
};
<Method>{
name: "is_just",
arguments: [],
selfType: "Maybe",
returnType: "Bool",
};
<Function>{
name: "foo",
arguments: [
{
name: "x",
type: "Number",
isSuspended: false,
hasDefault: false,
},
],
returnType: "Bool",
};
<Method>{
name: "baz",
arguments: [
{
name: "x",
type: "Number",
isSuspended: false,
hasDefault: false,
},
],
selfType: "Number",
returnType: "Number",
};
<Local>{
name: "x",
returnType: "Number",
};
<Local>{
name: "y",
returnType: "Number",
};
search/getSuggestionsDatabaseSent from client to the server to receive the full suggestions database.
The request always returns empty entries field with the correct
currentVersion. The suggestions are sent during the initial project
compilation as a part of
search/suggestionsDatabaseUpdate
notification.
interface SearchGetSuggestionsDatabaseParameters {}
interface SearchGetSuggestionsDatabaseResult {
/** The list of suggestions database entries. */
entries: SuggestionsDatabaseEntry[];
/** The version of the received suggestions database. */
currentVersion: number;
}
SuggestionsDatabaseError an error accessing the
suggestions databaseProjectNotFoundError project is not found in the
root directorysearch/invalidateSuggestionsDatabaseSent from client to the server to clean the suggestions database resetting the version.
interface SearchInvalidateSuggestionsDatabaseParameters {}
type SearchInvalidateSuggestionsDatabase = null;
SuggestionsDatabaseError an error accessing the
suggestions databasesearch/getSuggestionsDatabaseVersionSent from client to the server to receive the current version of the suggestions database.
interface SearchGetSuggestionsDatabaseVersionParameters {}
interface SearchGetSuggestionsDatabaseVersionResult {
/** The version of the suggestions database. */
currentVersion: number;
}
SuggestionsDatabaseError an error accessing the
suggestions databaseProjectNotFoundError project is not found in the
root directorysearch/suggestionsDatabaseUpdateSent from server to the client to inform about the change in the suggestions database.
interface SearchSuggestionsDatabaseUpdateNotification {
updates: SuggestionsDatabaseUpdate[];
currentVersion: number;
}
search/suggestionsOrderDatabaseUpdateSent from server to the client to inform about the change in the suggestions order database.
interface SearchSuggestionsOrderDatabaseUpdateNotification {
updates: SuggestionsOrderDatabaseUpdate[];
}
search/completionSent from client to the server to receive the autocomplete suggestion.
interface SearchCompletionParameters {
/** The edited file. */
file: Path;
/** The cursor position. */
position: Position;
/** Filter by methods with the provided self type. */
selfType?: string;
/** Filter by the return type. */
returnType?: string;
/** Filter by the suggestion types. */
tags?: SuggestionEntryType[];
/** Filter by `static` attribute of method suggestions. */
isStatic?: boolean;
}
The identifiers in results are guaranteed to be ordered by the specificity of
the type match.
interface SearchCompletionResult {
results: SuggestionId[];
currentVersion: number;
}
SuggestionsDatabaseError an error accessing the
suggestions databaseProjectNotFoundError project is not found in the
root directoryModuleNameNotResolvedError the module name
cannot be extracted from the provided file path parameterSuggestionNotFoundError the requested suggestion
was not found in the suggestions databaseThe input/output portion of the language server API deals with redirecting stdin/stdout/stderr of Enso programs to the clients of the language server. This is incredibly important for enabling the high levels of interactivity required by Enso Studio.
io/redirectStandardOutputThis message allows a client to redirect the standard output of Enso programs.
Once the standard output is redirected, the Language server will notify the
client about new output data by emitting io/standardOutputAppended messages.
interface IORedirectStandardOutputParameters {}
type IORedirectStandardOutput = null;
None
io/suppressStandardOutputThis message allows a client to suppress the redirection of the standard output.
interface IOSuppressStandardOutputParameters {}
type IOSuppressStandardOutputResult = null;
None
io/standardOutputAppendedSent from the server to the client to inform that new output data are available for the standard output.
interface IOStandardOutputAppendedNotification {
output: string;
}
io/redirectStandardErrorThis message allows a client to redirect the standard error of Enso programs.
Once the standard error is redirected, the Language server will notify the
client about new output data by emitting io/standardErrorAppended messages.
interface IORedirectStandardErrorParameters {}
type IORedirectStandardError = null;
None
io/suppressStandardErrorThis message allows a client to suppress the redirection of the standard error.
interface IOSuppressStandardErrorParameters {}
type IOSuppressStandardErrorResult = null;
None
io/standardErrorAppendedSent from the server to the client to inform that new output data are available for the standard error.
interface IOStandardErrorAppendedNotification {
output: string;
}
io/feedStandardInputThis message allows a client to feed the standard input of Enso programs.
interface IOFeedStandardInputParameters {
input: string;
isLineTerminated: boolean;
}
type IOFeedStandardInputResult = null;
None
io/waitingForStandardInputSent from the server to the client to inform that an Enso program is suspended
by IO.readln. This message is used to notify a client that she should feed the
standard input.
type IOWaitingForStandardInputNotification = null;
The library-related operations provide the Language Server with capabilities to check and modify project's edition settings, list editions published in a given edition, create local library projects which can be imported in the currently opened project and publish them.
editions/listAvailableLists editions available on the system.
Moreover, if update is set to true, it will download any new editions from
the repositories and include them in the result as well.
Currently, if
updatewastruebut some downloads failed, the endpoint will still return a success, just containing the editions that were already available. In the future it should emit warnings using proper notification channels.
interface EditionsListAvailableParameters {
update: boolean;
}
interface EditionsListAvailableResult {
editionNames: string[];
}
editions/resolveResolves settings implied by the edition.
Currently, it only resolves the engine version, as only it is needed, but other settings may be added if necessary.
interface EditionsResolveParameters {
edition: EditionReference;
}
interface EditionsResolveResult {
engineVersion: string;
}
EditionNotFoundError indicates that the requested
edition, or some edition referenced in the ancestors of the edition being
resolved, could not be found.FileSystemError to signal a generic, unrecoverable
file-system error.editions/getProjectSettingsReturns the currently set edition-related settings of the project.
Currently, it only returns the parent edition and local library preference. Once more advanced edition settings are to be supported in the IDE, this endpoint will be extended.
interface EditionsGetProjectSettingsParameters {}
interface EditionsGetProjectSettingsResult {
parentEdition?: string;
preferLocalLibraries: boolean;
}
The parentEdition may be missing if it is not set. It is possible to manually
edit the pacakge.yaml and generate a valid edition config that does not
specify a parent edition.
editions/setProjectParentEditionSets the parent edition of the project to a specific edition.
This change may even change the version of the engine associated with the
project, so for the changes to take effect, the language server may need to be
restarted. The endpoint only modifies the pacakge.yaml file, which is
preloaded in the Language Server, so it is IDE's responsibility to re-open the
project.
It returns an optional field needsRestart which specifies whether the Language
Server needs to be restarted for the change to take effect. If the field is
missing, it should be treated as set to false. In the current version it is
always set to true.
interface EditionsSetProjectParentEditionParameters {
newEditionName: string;
}
interface EditionsSetProjectParentEditionResult {
needsRestart?: boolean;
}
EditionNotFoundError indicates that the requested
edition could not be found.FileSystemError to signal a generic, unrecoverable
file-system error.editions/setProjectLocalLibrariesPreferenceSets the prefer-local-libraries setting of the project, which specifies if
libraries from ENSO_HOME/libraries should take precedence over the ones
defined in the edition.
This may change which libraries should be loaded in the project. In the future it may be possible that this reload could happen dynamically, however currently, the language server needs to be restarted (in the same way as for
editions/setProjectParentEdition) for the changes to take effect.
It returns an optional field needsRestart which specifies whether the Language
Server needs to be restarted for the change to take effect. If the field is
missing, it should be treated as set to false. In the current version it is
always set to true.
interface EditionsSetProjectLocalLibrariesPreferenceParameters {
preferLocalLibraries: boolean;
}
interface EditionsSetProjectLocalLibrariesPreferenceResult {
needsRestart?: boolean;
}
FileSystemError to signal a generic, unrecoverable
file-system error.editions/listDefinedLibrariesLists all libraries defined in an edition (or all of its parents).
This can be used to display which libraries can be downloaded / added to the project.
This does not include local libraries not defined explicitly in the project's
edition, even if they can be resolved as per prefer-local-libraries setting.
To get local libraries that are not directly referenced in the edition, use
library/listLocal instead.
interface EditionsListDefinedLibrariesParameters {
edition: EditionReference;
}
interface EditionsListDefinedLibrariesResult {
availableLibraries: LibraryEntry[];
}
EditionNotFoundError indicates that the requested
edition, or an edition referenced in one of its parents, could not be found.FileSystemError to signal a generic, unrecoverable
file-system error.editions/listDefinedComponentsLists all the component groups defined in an edition.
interface EditionsListDefinedComponentsParameters {
edition: EditionReference;
}
interface EditionsListDefinedComponentsResult {
availableComponents: LibraryComponentGroup[];
}
EditionNotFoundError indicates that the requested
edition, or an edition referenced in one of its parents, could not be found.FileSystemError to signal a generic, unrecoverable
file-system error.library/listLocalLists all local libraries available in the system.
interface LibraryListLocalParameters {}
interface LibraryListLocalResult {
localLibraries: LibraryEntry[];
}
FileSystemError to signal a generic, unrecoverable
file-system error.library/createCreates a new project package, but placed not in the projects directory, but in the local libraries directory, so that other projects (including the current one) that can resolve local libraries will be able to import it.
The created library package inherits all edition settings from the current project.
The endpoint just returns an empty message at success. Once this operation
finishes, the IDE can add the import import <namespace>.<name> to the open
file which will import the newly created library (the IDE must also ensure that
prefer-local-libraries is set to true or otherwise, it must add a proper
override to its own edition file to see this local library). Once the import is
added, the library will be loaded and its content root will be sent in a
file/rootAdded notification.
interface LibraryCreateParameters {
namespace: string;
name: string;
authors: Contact[];
maintainers: Contact[];
license: string;
}
type LibraryCreateResult = null;
InvalidLibraryName to signal that the selected
library name is not valid.LibraryAlreadyExists to signal that a library with
the given namespace and name already exists.FileSystemError to signal a generic, unrecoverable
file-system error.library/getMetadataGets metadata associated with a specific library version.
If the version is LocalLibraryVersion, it will try to read the manifest file
of the local library and return an empty result if the manifest does not exist.
If the version is PublishedLibraryVersion, it will fetch the manifest from the
library repository. A cached manifest may also be used, if it is available.
All returned fields are optional, as they may be missing.
interface LibraryGetMetadataParameters {
namespace: string;
name: string;
version: LibraryVersion;
}
interface LibraryGetMetadataResult {
description?: string;
tagLine?: string;
}
LocalLibraryNotFound to signal that a local library
with the given name does not exist on the local libraries path.InvalidSemverVersion to signal that the provided
version string is not a valid semver version.FileSystemError to signal a generic, unrecoverable
file-system error.library/setMetadataSets metadata associated with a local library that will be used for publishing.
All metadata fields are optional. If a field is not set in the parameters, it will be removed from the metadata (if it was present before).
interface LibrarySetMetadataParameters {
namespace: string;
name: string;
description?: string;
tagLine?: string;
}
type LibrarySetMetadataResult = null;
LocalLibraryNotFound to signal that a local library
with the given name does not exist on the local libraries path.FileSystemError to signal a generic, unrecoverable
file-system error.library/getPackageGets the package config associated with a specific library version.
If the version is LocalLibraryVersion, it will try to read the package file of
the local library and return an empty result if the manifest does not exist.
If the version is PublishedLibraryVersion, it will fetch the package config
from the library repository. A cached package config may also be used, if it is
available.
All returned fields are optional, as they may be missing.
interface LibraryGetPackageParameters {
namespace: string;
name: string;
version: LibraryVersion;
}
interface LibraryGetPackageResult {
license?: string;
componentGroups?: LibraryComponentGroups;
}
LocalLibraryNotFound to signal that a local library
with the given name does not exist on the local libraries path.InvalidSemverVersion to signal that the provided
version string is not a valid semver version.FileSystemError to signal a generic, unrecoverable
file-system error.library/publishPublishes a library located in the local libraries directory to the main Enso library repository.
If bumpVersionAfterPublish is set to true, after publishing the library, its
version is bumped automatically, so that future publications will not clash
versions. This is a temporary solution and in the longer-term it should be
replaced with separate settings allowing to arbitrarily modify the library
version from the IDE.
The uploadUrl is the URL of the library repository that accepts library
uploads.
The metadata for publishing the library can be set with
library/setMetadata. If it was not set, the publish
operation will still proceed, but that metadata will be missing.
interface LibraryPublishParameters {
namespace: string;
name: string;
authToken: string;
uploadUrl: string;
bumpVersionAfterPublish?: boolean;
}
type LibraryPublishResult = null;
LocalLibraryNotFound to signal that a local library
with the given name does not exist on the local libraries path.LibraryPublishError to signal that the server did
not accept to publish the library (for example because a library with the same
version already exists).LibraryRepositoryAuthenticationError
to signal an authentication failure.LibraryUploadError to signal that the upload
operation has failed, for network-related reasons.FileSystemError to signal a generic, unrecoverable
file-system error.library/preinstallEnsures that the requested library and all of its (transitive) dependencies, at versions as resolved by the current project's edition, are downloaded.
Once this operation completes, the library import can be added to the project and it is guaranteed that (unless there were unexpected changes to the system, like files being manually deleted) no further downloads will be needed, so that the import should load quickly.
This can be used by the IDE to predownload the library that is about to be added to a project, to avoid freezing the compiler for the time the dependencies are being downloaded.
While this operation is in progress, multiple series of task/* notifications
may be sent, indicating progress of particular components being downloaded and
installed.
interface LibraryPreinstallParameters {
namespace: string;
name: string;
}
type LibraryPreinstallResult = null;
LibraryNotResolved to signal that the requested
library or one of its dependencies could not be resolved.DependencyDiscoveryError to signal that
dependencies of the library could not be established.LibraryDownloadError to signal that the download
operation has failed, for network-related reasons, or because the library was
missing in the repository. The error includes the name and version of the
library that failed to download - as when preinstalling a specific library the
failure may be tied not to that library itself but also one of its
dependencies.FileSystemError to signal a generic, unrecoverable
file-system error.runtime/getComponentGroupsSent from the client to the server to get the list of component groups available in runtime.
The engine is started with an empty list of libraries loaded. It means that the
request should be sent after the first
executionContext/executionComplete
notification indicating that all the libraries are loaded, and the component
group list is populated. If the request is sent before the first notification,
the response may be empty or not contain all available components.
interface RuntimeGetComponentGroupsParameters {}
interface RuntimeGetComponentGroupsResult {
componentGroups: LibraryComponentGroup[];
}
None
profiling/startSent from the client to the server to initiate gathering the profiling data.
This command should be followed by the profiling/stop
request to store the gathered data. After the profiling is started, subsequent
profiling/start commands will do nothing.
interface ProfilingStartParameters {
/** Also take a memory snapshot when the profiling is stopped. */
memorySnapshot?: boolean;
}
interface ProfilingStartResult {}
None
profiling/stopSent from the client to the server to finish gathering the profiling data. The
collected data is stored in the ENSO_DATA_DIRECTORY/profiling directory. After
the profiling is stopped, subsequent profiling/stop commands will do nothing.
interface ProfilingStopParameters {}
interface ProfilingStopResult {}
None
ai/completion_v2Sent from the client to the server to ask the AI model the code suggestion.
interface AiCompletionParameters {
/** The execution context id to use for executing expressions. */
contextId: UUID;
/**
* The expression providing the execution scope. The same as `expressionId`
* parameter of `executionContext/executeExpression` method.
*/
expressionId: UUID;
/** The user prompt. */
prompt: string;
/** The system prompt describing the AI role. */
systemPrompt?: string;
/** The AI model to use. */
model?: string;
}
type AiCompletionResult = AiCompletionResultSuccess | AiCompletionResultFailure;
interface AiCompletionResultSuccess {
/** The code of the function producing the desired result. */
fn: string;
/** The code of how to call the suggested function. */
fnCall: string;
}
interface AiCompletionResultFailure {
/**
* The explanation given by the AI model for why it was unable to provide the
* answer.
*/
reason: string;
}
AiHttpError Signals about an error during the processing of
AI http respnse.AiEvaluationError Signals about an error during the
evaluation of expression requested by AI.ai/completionProgressSent from server to the client to inform about the progress of the
ai/completion request.
interface AiCompletionProgressNotification {
/** Code snippte that AI model requested to evaluate. */
code: string;
/** Explanation given by the AI model why it needs an extra information. */
reason: string;
/**
* The id of the visualization being executed. When evaluated, the
* visualization update will contain the result of the executed expression.
*/
visualizationId: UUID;
}
The language server component also has its own set of errors. This section is not a complete specification and will be updated as new errors are added.
Besides the required code and message fields, the errors may have a data
field which can store additional error-specific payload.
ErrorAn error container for the binary connection that contains a code, message and payload.
namespace org.enso.languageserver.protocol.binary;
table Error {
// A unique error code identifying error type.
code: int;
// An error message.
message: string (required);
// Additional payloads for the error.
data : ErrorPayload;
}
union ErrorPayload {
...
}
Note:
ErrorPayload will be extended with additional payloads as
necessary.AccessDeniedErrorIt signals that a user doesn't have access to a resource.
"error" : {
"code" : 100,
"message" : "Access denied"
}
FileSystemErrorThis error signals generic file system errors.
"error" : {
"code" : 1000,
"message" : string
}
ContentRootNotFoundErrorThe error informs that the requested content root cannot be found.
"error" : {
"code" : 1001,
"message" : "Content root not found"
}
FileNotFoundIt signals that requested file doesn't exist.
"error" : {
"code" : 1003,
"message" : "File not found"
}
FileExistsIt signals that file already exists.
"error" : {
"code" : 1004,
"message" : "File already exists"
}
OperationTimeoutErrorIt signals that IO operation timed out.
"error" : {
"code" : 1005,
"message" : "IO operation timeout"
}
NotDirectoryIt signals that provided path is not a directory.
"error" : {
"code" : 1006,
"message" : "Path is not a directory"
}
NotFileIt signals that the provided path is not a file.
"error" : {
"code" : 1007,
"message" : "Path is not a file"
}
CannotOverwriteSignals that a streaming file write cannot overwrite a portion of the requested file.
"error" : {
"code" : 1008,
"message" : "Cannot overwrite the file without `overwriteExisting` set"
}
ReadOutOfBoundsSignals that the requested file read was out of bounds for the file's size.
"error" : {
"code" : 1009
"message" : "Read is out of bounds for the file"
"payload" : {
"fileLength" : 0
}
}
CannotDecodeSignals that the project configuration cannot be decoded.
"error" : {
"code" : 1010
"message" : "Cannot decode the project configuration"
}
namespace org.enso.languageserver.protocol.binary;
table ReadOutOfBoundsError {
// The actual length of the file.
fileLength : ulong (required);
}
StackItemNotFoundErrorIt signals that provided stack item was not found.
"error" : {
"code" : 2001,
"message" : "Stack item not found"
}
ContextNotFoundErrorIt signals that provided context was not found.
"error" : {
"code" : 2002,
"message" : "Context not found"
}
EmptyStackErrorIt signals that stack is empty.
"error" : {
"code" : 2003,
"message" : "Stack is empty"
}
InvalidStackItemErrorIt signals that stack is invalid in this context.
"error" : {
"code" : 2004,
"message" : "Invalid stack item"
}
ModuleNotFoundErrorIt signals that the given module cannot be found.
"error" : {
"code" : 2005,
"message" : "Module not found [Foo.Bar.Baz]"
}
VisualizationNotFoundErrorIt signals that the visualization cannot be found.
"error" : {
"code" : 2006,
"message" : "Visualization not found"
}
VisualizationExpressionErrorIt signals that the expression specified in the VisualizationConfiguration
cannot be evaluated. The error contains an optional data field of type
Diagnostic providing error details.
"error" : {
"code" : 2007,
"message" : "Evaluation of the visualization expression failed [i is not defined]"
"payload" : {
"kind" : "Error",
"message" : "i is not defined",
"path" : null,
"location" : {
"start" : {
"line" : 0,
"character" : 8
},
"end" : {
"line" : 0,
"character" : 9
}
},
"expressionId" : "aa1f75c4-8c4d-493d-a6a7-72123a52f084",
"stack" : []
}
}
FileNotOpenedErrorSignals that a file wasn't opened.
"error" : {
"code" : 3001,
"message" : "File not opened"
}
TextEditValidationErrorSignals that validation has failed for a series of edits.
"error" : {
"code" : 3002,
"message" : "The start position is after the end position"
}
InvalidVersionErrorSignals that version provided by a client doesn't match to the version computed by the server.
"error" : {
"code" : 3003,
"message" : "Invalid version [client version: ade2967cab172183d1a67ea40cb8e92e23218764bc9934c3795fcea5, server version: 7602967cab172183d1a67ea40cb8e92e23218764bc9934c3795fcea5]"
}
WriteDeniedErrorSignals that the client doesn't hold write lock to the buffer.
"error" : {
"code" : 3004,
"message" : "Write denied"
}
CapabilityNotAcquiredSignals that requested capability is not acquired.
"error" : {
"code" : 5001,
"message" : "Capability not acquired"
}
SessionNotInitialisedErrorSignals that the request cannot be proccessed, because the session is not initialized.
"error" : {
"code" : 6001,
"message" : "Session not initialised"
}
SessionAlreadyInitialisedErrorSignals that the session is already initialized.
"error" : {
"code" : 6002,
"message" : "Session already initialised"
}
ResourcesInitializationErrorSignals about an error in the Language Server initialization process.
"error" : {
"code" : 6003,
"message" : "Failed to initialize the Language Server resources"
}
SuggestionsDatabaseErrorSignals about an error accessing the suggestions database.
"error" : {
"code" : 7001,
"message" : "Suggestions database error"
}
ProjectNotFoundErrorSignals that the project could not be found in the root directory.
"error" : {
"code" : 7002,
"message" : "Project not found in the root directory"
}
ModuleNameNotResolvedErrorSignals that the module name could not be resolved for the given file.
"error" : {
"code" : 7003,
"message" : "Module name can't be resolved for the given file"
}
SuggestionNotFoundErrorSignals that the requested suggestion could not be found.
"error" : {
"code" : 7004,
"message" : "Requested suggestion was not found"
}
EditionNotFoundErrorSignals that an edition could not be found.
Its payload includes the name of the edition that could not be found.
"error" : {
"code" : 8001,
"message" : "Edition [<name>] could not be found.",
"payload" : {
"editionName": "<name>"
}
}
LibraryAlreadyExistsSignals that a local library with the specified namespace and name combination already exists, so it cannot be created again.
"error" : {
"code" : 8002,
"message" : "Library [<namespace>.<name>] already exists."
}
LibraryRepositoryAuthenticationErrorSignals that authentication to the library repository was declined.
"error" : {
"code" : 8003,
"message" : "Authentication failed: [message]"
}
LibraryPublishErrorSignals that a request to the library repository failed.
"error" : {
"code" : 8004,
"message" : "Could not publish the library: [message]"
}
LibraryUploadErrorSignals that uploading the library failed for network-related reasons.
"error" : {
"code" : 8005,
"message" : "Could not upload the library: [message]"
}
LibraryDownloadErrorSignals that downloading the library failed for network-related reasons or that it was not available in the repository.
"error" : {
"code" : 8006,
"message" : "Could not download the library: [message]",
"payload" : {
"namespace" : "<namespace>",
"name" : "<name>",
"version": "<version>"
}
}
LocalLibraryNotFoundSignals that a local library with the specified namespace and name combination was not found on the local libraries path.
"error" : {
"code" : 8007,
"message" : "Local library [<namespace>.<name>] has not been found."
}
LibraryNotResolvedSignals that a library could not be resolved - it was not defined in the edition and the settings did not allow to resolve local libraries or it did not exist there either.
"error" : {
"code" : 8008,
"message" : "Could not resolve [<namespace>.<name>].",
"payload" : {
"namespace" : "<namespace>",
"name" : "<name>"
}
}
InvalidLibraryNameSignals that the chosen library name is invalid.
It contains a suggestion of a similar name that is valid.
For example for FooBar it will suggest Foo_Bar.
"error" : {
"code" : 8009,
"message" : "[<name>] is not a valid name: <reason>.",
"payload" : {
"suggestedName" : "<fixed-name>"
}
}
DependencyDiscoveryErrorSignals that the library preinstall endpoint could not properly find dependencies of the requested library.
"error" : {
"code" : 8010,
"message" : "Error occurred while discovering dependencies: <reason>."
}
InvalidSemverVersionSignals that the provided version string is not a valid semver version. The message contains the invalid version in the payload.
"error" : {
"code" : 8011,
"message" : "[<invalid-version>] is not a valid semver version.",
"payload" : {
"version" : "<invalid-version>"
}
}
ExpressionNotFoundErrorSignals that the expression cannot be found by the provided id.
"error" : {
"code" : 9001,
"message" : "Expression not found by id [<expression-id>]"
}
FailedToApplyEditsSignals that the refactoring operation was not able to apply generated edits.
"error" : {
"code" : 9002,
"message" : "Failed to apply edits to module [<module-name>]"
}
RefactoringNotSupportedSignals that the refactoring of the given expression is not supported.
"error" : {
"code" : 9003,
"message" : "Refactoring not supported for expression [<expression-id>]"
}
ProjectRenameFailedSignals that the project rename failed.
"error" : {
"code" : 9004,
"message" : "Project rename failed [<oldName>, <newName>]"
}
DefinitionAlreadyExistsSignals that the definition with the provided name already exists in the scope.
"error" : {
"code" : 9005,
"message" : "Definition [<name>] already exists"
}
AiHttpErrorSignals about an error during the processing of AI http respnse.
"error" : {
"code" : 10001,
"message" : "Failed to process HTTP response",
"payload" : {
"reason" : "<Failure reason>",
"request" : "<HTTP request sent>",
"response" : "<HTTP response received>"
}
}
AiEvaluationErrorSignals about an error during the evaluation of expression requested by AI.
"error" : {
"code" : 10002,
"message" : "Failed to execute expression",
"payload" : {
"expression" : "<Evaluated expression>",
"error" : "<The evaluation error message>"
}
}