mirror of
https://github.com/enso-org/enso.git
synced 2024-12-21 03:41:47 +03:00
5720 lines
123 KiB
Markdown
5720 lines
123 KiB
Markdown
---
|
|
layout: developer-doc
|
|
title: Enso Protocol Language Server Message Specification
|
|
category: language-server
|
|
tags: [language-server, protocol, specification]
|
|
order: 4
|
|
---
|
|
|
|
# Enso Protocol Language Server Message Specification
|
|
|
|
This document contains the specification of the Enso protocol messages that
|
|
pertain to the language server component. Please familiarise yourself with the
|
|
[common](./protocol-common.md) 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](./protocol-architecture).
|
|
|
|
<!-- MarkdownTOC levels="2,3" autolink="true" -->
|
|
|
|
- [Types](#types)
|
|
- [`ExpressionId`](#expressionid)
|
|
- [`ContextId`](#contextid)
|
|
- [`StackItem`](#stackitem)
|
|
- [`MethodPointer`](#methodpointer)
|
|
- [`ProfilingInfo`](#profilinginfo)
|
|
- [`ExpressionUpdate`](#expressionupdate)
|
|
- [`ExpressionUpdatePayload`](#expressionupdatepayload)
|
|
- [`VisualisationConfiguration`](#visualisationconfiguration)
|
|
- [`VisualisationExpression`](#visualisationexpression)
|
|
- [`SuggestionEntryArgument`](#suggestionentryargument)
|
|
- [`SuggestionEntry`](#suggestionentry)
|
|
- [`SuggestionEntryType`](#suggestionentrytype)
|
|
- [`SuggestionId`](#suggestionid)
|
|
- [`DocSection`](#docsection)
|
|
- [`SuggestionsDatabaseEntry`](#suggestionsdatabaseentry)
|
|
- [`FieldAction`](#fieldaction)
|
|
- [`FieldUpdate`](#fieldupdate)
|
|
- [`SuggestionArgumentUpdate`](#suggestionargumentupdate)
|
|
- [`SuggestionsDatabaseUpdate`](#suggestionsdatabaseupdate)
|
|
- [`SuggestionsOrderDatabaseUpdate`](#suggestionsorderdatabaseupdate)
|
|
- [`Export`](#export)
|
|
- [`File`](#file)
|
|
- [`DirectoryTree`](#directorytree)
|
|
- [`FileAttributes`](#fileattributes)
|
|
- [`UTCDateTime`](#utcdatetime)
|
|
- [`FileEventKind`](#fileeventkind)
|
|
- [`Position`](#position)
|
|
- [`Range`](#range)
|
|
- [`TextEdit`](#textedit)
|
|
- [`DiagnosticType`](#diagnostictype)
|
|
- [`StackTraceElement`](#stacktraceelement)
|
|
- [`Diagnostic`](#diagnostic)
|
|
- [`SHA3-224`](#sha3-224)
|
|
- [`FileEdit`](#fileedit)
|
|
- [`FileContents`](#filecontents)
|
|
- [`FileSystemObject`](#filesystemobject)
|
|
- [`WorkspaceEdit`](#workspaceedit)
|
|
- [`EnsoDigest`](#ensodigest)
|
|
- [`FileSegment`](#filesegment)
|
|
- [`ContentRoot`](#contentroot)
|
|
- [`LibraryEntry`](#libraryentry)
|
|
- [`LibraryVersion`](#libraryversion)
|
|
- [`Contact`](#contact)
|
|
- [`EditionReference`](#editionreference)
|
|
- [`LibraryComponentGroups`](#librarycomponentgroups)
|
|
- [`LibraryComponentGroup`](#librarycomponentgroup)
|
|
- [`LibraryComponent`](#librarycomponent)
|
|
- [Connection Management](#connection-management)
|
|
- [`session/initProtocolConnection`](#sessioninitprotocolconnection)
|
|
- [`session/initBinaryConnection`](#sessioninitbinaryconnection)
|
|
- [Capability Management](#capability-management)
|
|
- [`capability/acquire`](#capabilityacquire)
|
|
- [`capability/release`](#capabilityrelease)
|
|
- [`capability/granted`](#capabilitygranted)
|
|
- [`capability/forceReleased`](#capabilityforcereleased)
|
|
- [Capabilities](#capabilities)
|
|
- [`text/canEdit`](#textcanedit)
|
|
- [`file/receivesTreeUpdates`](#filereceivestreeupdates)
|
|
- [`executionContext/canModify`](#executioncontextcanmodify)
|
|
- [`executionContext/receivesUpdates`](#executioncontextreceivesupdates)
|
|
- [`search/receivesSuggestionsDatabaseUpdates`](#searchreceivessuggestionsdatabaseupdates)
|
|
- [File Management Operations](#file-management-operations)
|
|
- [`file/write`](#filewrite)
|
|
- [`file/read`](#fileread)
|
|
- [`file/writeBinary`](#filewritebinary)
|
|
- [`file/readBinary`](#filereadbinary)
|
|
- [`file/writeBytes`](#filewritebytes)
|
|
- [`file/readBytes`](#filereadbytes)
|
|
- [`file/create`](#filecreate)
|
|
- [`file/delete`](#filedelete)
|
|
- [`file/copy`](#filecopy)
|
|
- [`file/move`](#filemove)
|
|
- [`file/exists`](#fileexists)
|
|
- [`file/tree`](#filetree)
|
|
- [`file/list`](#filelist)
|
|
- [`file/info`](#fileinfo)
|
|
- [`file/checksum`](#filechecksum)
|
|
- [`file/checksumBytes`](#filechecksumbytes)
|
|
- [`file/event`](#fileevent)
|
|
- [`file/rootAdded`](#filerootadded)
|
|
- [`file/rootRemoved`](#filerootremoved)
|
|
- [Version Control System](#vcs-operations)
|
|
- [`vcs/init`](#vcsinit)
|
|
- [`vcs/list`](#vcslist)
|
|
- [`vcs/restore`](#vcsrestore)
|
|
- [`vcs/save`](#vcssave)
|
|
- [`vcs/status`](#vcsstatus)
|
|
- [Text Editing Operations](#text-editing-operations)
|
|
- [`text/openFile`](#textopenfile)
|
|
- [`text/openBuffer`](#textopenbuffer)
|
|
- [`text/closeFile`](#textclosefile)
|
|
- [`text/save`](#textsave)
|
|
- [`text/applyEdit`](#textapplyedit)
|
|
- [`text/applyExpressionValue`](#textapplyexpressionvalue)
|
|
- [`text/didChange`](#textdidchange)
|
|
- [`text/autoSave`](#textautosave)
|
|
- [Workspace Operations](#workspace-operations)
|
|
- [`workspace/projectInfo`](#workspaceprojectinfo)
|
|
- [Monitoring](#monitoring)
|
|
- [`heartbeat/ping`](#heartbeatping)
|
|
- [`heartbeat/init`](#heartbeatinit)
|
|
- [Refactoring](#refactoring)
|
|
- [`refactoring/renameProject`](#refactoringrenameproject)
|
|
- [Execution Management Operations](#execution-management-operations)
|
|
- [Execution Management Example](#execution-management-example)
|
|
- [Create Execution Context](#create-execution-context)
|
|
- [Push Item](#push-item)
|
|
- [Pop Item](#pop-item)
|
|
- [`executionContext/create`](#executioncontextcreate)
|
|
- [`executionContext/destroy`](#executioncontextdestroy)
|
|
- [`executionContext/fork`](#executioncontextfork)
|
|
- [`executionContext/push`](#executioncontextpush)
|
|
- [`executionContext/pop`](#executioncontextpop)
|
|
- [`executionContext/recompute`](#executioncontextrecompute)
|
|
- [`executionContext/getComponentGroups`](#executioncontextgetcomponentgroups)
|
|
- [`executionContext/expressionUpdates`](#executioncontextexpressionupdates)
|
|
- [`executionContext/executionFailed`](#executioncontextexecutionfailed)
|
|
- [`executionContext/executionComplete`](#executioncontextexecutioncomplete)
|
|
- [`executionContext/executionStatus`](#executioncontextexecutionstatus)
|
|
- [`executionContext/executeExpression`](#executioncontextexecuteexpression)
|
|
- [`executionContext/attachVisualisation`](#executioncontextattachvisualisation)
|
|
- [`executionContext/detachVisualisation`](#executioncontextdetachvisualisation)
|
|
- [`executionContext/modifyVisualisation`](#executioncontextmodifyvisualisation)
|
|
- [`executionContext/visualisationUpdate`](#executioncontextvisualisationupdate)
|
|
- [`executionContext/visualisationEvaluationFailed`](#executioncontextvisualisationevaluationfailed)
|
|
- [Search Operations](#search-operations)
|
|
- [Suggestions Database Example](#suggestions-database-example)
|
|
- [`search/getSuggestionsDatabase`](#searchgetsuggestionsdatabase)
|
|
- [`search/invalidateSuggestionsDatabase`](#searchinvalidatesuggestionsdatabase)
|
|
- [`search/getSuggestionsDatabaseVersion`](#searchgetsuggestionsdatabaseversion)
|
|
- [`search/suggestionsDatabaseUpdate`](#searchsuggestionsdatabaseupdate)
|
|
- [`search/suggestionsOrderDatabaseUpdate`](#searchsuggestionsorderdatabaseupdate)
|
|
- [`search/completion`](#searchcompletion)
|
|
- [Input/Output Operations](#inputoutput-operations)
|
|
- [`io/redirectStandardOutput`](#ioredirectstandardoutput)
|
|
- [`io/suppressStandardOutput`](#iosuppressstandardoutput)
|
|
- [`io/standardOutputAppended`](#iostandardoutputappended)
|
|
- [`io/redirectStandardError`](#ioredirectstandarderror)
|
|
- [`io/suppressStandardError`](#iosuppressstandarderror)
|
|
- [`io/standardErrorAppended`](#iostandarderrorappended)
|
|
- [`io/feedStandardInput`](#iofeedstandardinput)
|
|
- [`io/waitingForStandardInput`](#iowaitingforstandardinput)
|
|
- [Library-Related Operations](#library-related-operations)
|
|
- [`editions/listAvailable`](#editionslistavailable)
|
|
- [`editions/resolve`](#editionsresolve)
|
|
- [`editions/getProjectSettings`](#editionsgetprojectsettings)
|
|
- [`editions/setProjectParentEdition`](#editionssetprojectparentedition)
|
|
- [`editions/setProjectLocalLibrariesPreference`](#editionssetprojectlocallibrariespreference)
|
|
- [`editions/listDefinedLibraries`](#editionslistdefinedlibraries)
|
|
- [`editions/listDefinedComponents`](#editionslistdefinedcomponents)
|
|
- [`library/listLocal`](#librarylistlocal)
|
|
- [`library/create`](#librarycreate)
|
|
- [`library/getMetadata`](#librarygetmetadata)
|
|
- [`library/setMetadata`](#librarysetmetadata)
|
|
- [`library/getPackage`](#librarygetpackage)
|
|
- [`library/publish`](#librarypublish)
|
|
- [`library/preinstall`](#librarypreinstall)
|
|
- [Errors](#errors-75)
|
|
- [`Error`](#error)
|
|
- [`AccessDeniedError`](#accessdeniederror)
|
|
- [`FileSystemError`](#filesystemerror)
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror)
|
|
- [`FileNotFound`](#filenotfound)
|
|
- [`FileExists`](#fileexists)
|
|
- [`OperationTimeoutError`](#operationtimeouterror)
|
|
- [`NotDirectory`](#notdirectory)
|
|
- [`NotFile`](#notfile)
|
|
- [`CannotOverwrite`](#cannotoverwrite)
|
|
- [`ReadOutOfBounds`](#readoutofbounds)
|
|
- [`CannotDecode`](#cannotdecode)
|
|
- [`StackItemNotFoundError`](#stackitemnotfounderror)
|
|
- [`ContextNotFoundError`](#contextnotfounderror)
|
|
- [`EmptyStackError`](#emptystackerror)
|
|
- [`InvalidStackItemError`](#invalidstackitemerror)
|
|
- [`ModuleNotFoundError`](#modulenotfounderror)
|
|
- [`VisualisationNotFoundError`](#visualisationnotfounderror)
|
|
- [`VisualisationExpressionError`](#visualisationexpressionerror)
|
|
- [`FileNotOpenedError`](#filenotopenederror)
|
|
- [`TextEditValidationError`](#texteditvalidationerror)
|
|
- [`InvalidVersionError`](#invalidversionerror)
|
|
- [`WriteDeniedError`](#writedeniederror)
|
|
- [`CapabilityNotAcquired`](#capabilitynotacquired)
|
|
- [`SessionNotInitialisedError`](#sessionnotinitialisederror)
|
|
- [`SessionAlreadyInitialisedError`](#sessionalreadyinitialisederror)
|
|
- [`ResourcesInitializationError`](#resourcesinitializationerror)
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror)
|
|
- [`ProjectNotFoundError`](#projectnotfounderror)
|
|
- [`ModuleNameNotResolvedError`](#modulenamenotresolvederror)
|
|
- [`SuggestionNotFoundError`](#suggestionnotfounderror)
|
|
- [`EditionNotFoundError`](#editionnotfounderror)
|
|
- [`LibraryAlreadyExists`](#libraryalreadyexists)
|
|
- [`LibraryRepositoryAuthenticationError`](#libraryrepositoryauthenticationerror)
|
|
- [`LibraryPublishError`](#librarypublisherror)
|
|
- [`LibraryUploadError`](#libraryuploaderror)
|
|
- [`LibraryDownloadError`](#librarydownloaderror)
|
|
- [`LocalLibraryNotFound`](#locallibrarynotfound)
|
|
- [`LibraryNotResolved`](#librarynotresolved)
|
|
- [`InvalidLibraryName`](#invalidlibraryname)
|
|
- [`DependencyDiscoveryError`](#dependencydiscoveryerror)
|
|
- [`InvalidSemverVersion`](#invalidsemverversion)
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
## Types
|
|
|
|
There are a number of types that are used only within the language server's
|
|
protocol messages. These are specified here.
|
|
|
|
### `ExpressionId`
|
|
|
|
An identifier used for Enso expressions.
|
|
|
|
```typescript
|
|
type ExpressionId = UUID;
|
|
```
|
|
|
|
### `ContextId`
|
|
|
|
An identifier used for execution contexts.
|
|
|
|
```typescript
|
|
type ContextId = UUID;
|
|
```
|
|
|
|
### `StackItem`
|
|
|
|
A 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".
|
|
|
|
```typescript
|
|
type StackItem = ExplicitCall | LocalCall;
|
|
|
|
interface ExplicitCall {
|
|
methodPointer: MethodPointer;
|
|
thisArgumentExpression?: String;
|
|
positionalArgumentsExpressions: String[];
|
|
}
|
|
|
|
interface LocalCall {
|
|
expressionId: ExpressionId;
|
|
}
|
|
```
|
|
|
|
### `MethodPointer`
|
|
|
|
Points to a method definition.
|
|
|
|
```typescript
|
|
interface MethodPointer {
|
|
/** The fully qualified module name. */
|
|
module: String;
|
|
|
|
/** The type on which the method is defined. */
|
|
definedOnType: String;
|
|
|
|
/** The method name. */
|
|
name: String;
|
|
}
|
|
```
|
|
|
|
### `ProfilingInfo`
|
|
|
|
Profiling information on an executed expression. It is implemented as a union as
|
|
additional types of information will be added in the future.
|
|
|
|
```typescript
|
|
type ProfilingInfo = ExecutionTime;
|
|
```
|
|
|
|
Where:
|
|
|
|
```typescript
|
|
interface ExecutionTime {
|
|
/** The time elapsed during the expression's evaluation, in nanoseconds */
|
|
nanoTime: Number;
|
|
}
|
|
```
|
|
|
|
### `ExpressionUpdate`
|
|
|
|
An update about the computed expression.
|
|
|
|
```typescript
|
|
interface ExpressionUpdate {
|
|
/**
|
|
* The id of updated expression.
|
|
*/
|
|
expressionId: ExpressionId;
|
|
|
|
/**
|
|
* The updated type of the expression.
|
|
*/
|
|
type?: String;
|
|
|
|
/**
|
|
* The updated pointer to the method call.
|
|
*/
|
|
methodPointer?: SuggestionId;
|
|
|
|
/**
|
|
* Profiling information about the expression.
|
|
*/
|
|
profilingInfo: ProfilingInfo[];
|
|
|
|
/**
|
|
* Wether or not the expression's value came from the cache.
|
|
*/
|
|
fromCache: bool;
|
|
|
|
/**
|
|
* An extra information about the computed value.
|
|
*/
|
|
payload: ExpressionUpdatePayload;
|
|
}
|
|
```
|
|
|
|
### `ExpressionUpdatePayload`
|
|
|
|
An information about the computed value.
|
|
|
|
```typescript
|
|
type ExpressionUpdatePayload = Value | DatafalowError | Panic | Pending;
|
|
|
|
/**
|
|
* An empty payload. Indicates that the expression was computed to a value.
|
|
*/
|
|
interface Value {}
|
|
|
|
/**
|
|
* 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 description and percentage (`0.0-1.0`) of completeness.
|
|
*/
|
|
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;
|
|
}
|
|
```
|
|
|
|
### `VisualisationConfiguration`
|
|
|
|
A configuration object for properties of the visualisation.
|
|
|
|
```typescript
|
|
interface VisualisationConfiguration {
|
|
/** An execution context of the visualisation. */
|
|
executionContextId: UUID;
|
|
|
|
/**
|
|
* A qualified name of the module containing the expression which creates
|
|
* visualisation.
|
|
*/
|
|
visualisationModule?: String;
|
|
|
|
/** An expression that creates a visualisation. */
|
|
expression: String | MethodPointer;
|
|
|
|
/** A list of arguments to pass to the visualization expression. */
|
|
positionalArgumentsExpressions?: string[];
|
|
}
|
|
```
|
|
|
|
### `SuggestionEntryArgument`
|
|
|
|
The argument of a [`SuggestionEntry`](#suggestionentry).
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
// 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. */
|
|
type: string;
|
|
/** Indicates whether the argument is lazy. */
|
|
isSuspended: bool;
|
|
/** Indicates whether the argument has default value. */
|
|
hasDefault: bool;
|
|
/** Optional default value. */
|
|
defaultValue?: string;
|
|
/** Optional list of possible values that this argument takes. */
|
|
tagValues?: string[];
|
|
}
|
|
```
|
|
|
|
### `SuggestionEntry`
|
|
|
|
The language construct that can be returned as a suggestion.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
// 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. */
|
|
reexport?: string;
|
|
|
|
/** The rendered HTML of the documentation string. */
|
|
documentationHtml?: string;
|
|
|
|
/** The documentation string divided into sections. */
|
|
documentationSections?: DocSection[];
|
|
}
|
|
|
|
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. */
|
|
reexport?: string;
|
|
|
|
/** The documentation string. */
|
|
documentation?: string;
|
|
|
|
/** The rendered HTML of the documentation string. */
|
|
documentationHtml?: string;
|
|
|
|
/** The documentation string divided into sections. */
|
|
documentationSections?: DocSection[];
|
|
}
|
|
|
|
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. */
|
|
reexport?: string;
|
|
|
|
/** The documentation string. */
|
|
documentation?: string;
|
|
|
|
/** The rendered HTML of the documentation string. */
|
|
documentationHtml?: string;
|
|
|
|
/** The documentation string divided into sections. */
|
|
documentationSections?: DocSection[];
|
|
}
|
|
|
|
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. */
|
|
reexport?: string;
|
|
|
|
/** The documentation string. */
|
|
documentation?: string;
|
|
|
|
/** The rendered HTML of the documentation string. */
|
|
documentationHtml?: string;
|
|
|
|
/** The documentation string divided into sections. */
|
|
documentationSections?: DocSection[];
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
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;
|
|
}
|
|
```
|
|
|
|
### `SuggestionEntryType`
|
|
|
|
The suggestion entry type that is used as a filter in search requests.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
// The kind of a suggestion.
|
|
type SuggestionEntryType =
|
|
| Module
|
|
| Type
|
|
| Constructor
|
|
| Method
|
|
| Function
|
|
| Local;
|
|
```
|
|
|
|
### `SuggestionId`
|
|
|
|
The suggestion entry id of the suggestions database.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type SuggestionId = number;
|
|
```
|
|
|
|
### `DocSection`
|
|
|
|
A single section of the documentation.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type DocSection = Tag | Paragraph | Keyed | Marked;
|
|
|
|
/** The documentation tag.
|
|
*
|
|
* {{{
|
|
* name text
|
|
* }}}
|
|
*
|
|
* @example
|
|
*
|
|
* {{{
|
|
* UNSTABLE
|
|
* DEPRECATED
|
|
* ALIAS Length
|
|
* }}}
|
|
*
|
|
*/
|
|
interface Tag {
|
|
/** The tag name. */
|
|
name: string;
|
|
|
|
/** The tag text. */
|
|
body: HTMLString;
|
|
}
|
|
|
|
/** The paragraph of the text.
|
|
*
|
|
* @example
|
|
*
|
|
* {{{
|
|
* Arbitrary text in the documentation comment.
|
|
*
|
|
* This is another paragraph.
|
|
* }}}
|
|
*
|
|
*/
|
|
interface Paragraph {
|
|
/** The elements that make up this paragraph. */
|
|
body: HTMLString;
|
|
}
|
|
|
|
/** The section that starts with the key followed by the colon and the body.
|
|
*
|
|
* {{{
|
|
* key: body
|
|
* }}}
|
|
*
|
|
* @example
|
|
*
|
|
* {{{
|
|
* Arguments:
|
|
* - one: the first
|
|
* - two: the second
|
|
* }}}
|
|
*
|
|
*
|
|
* {{{
|
|
* Icon: table-from-rows
|
|
* }}}
|
|
*
|
|
*/
|
|
interface Keyed {
|
|
/** The section key. */
|
|
key: string;
|
|
|
|
/** The elements that make up the body of the section. */
|
|
body: HTMLString;
|
|
}
|
|
|
|
/** The section that starts with the mark followed by the header and the body.
|
|
*
|
|
* {{{
|
|
* mark header
|
|
* body
|
|
* }}}
|
|
*
|
|
* @example
|
|
*
|
|
* {{{
|
|
* > Example
|
|
* This is how it's done.
|
|
* foo = bar baz
|
|
* }}}
|
|
*
|
|
* {{{
|
|
* ! Notice
|
|
* This is important.
|
|
* }}}
|
|
*/
|
|
interface Marked {
|
|
/** The section mark. */
|
|
mark: Mark;
|
|
|
|
/** The section header. */
|
|
header?: string;
|
|
|
|
/** The elements that make up the body of the section. */
|
|
body: HTMLString;
|
|
}
|
|
|
|
/** Text rendered as HTML (may contain HTML tags). */
|
|
type HTMLString = string;
|
|
|
|
type Mark = "Important" | "Info" | "Example";
|
|
```
|
|
|
|
### `SuggestionsDatabaseEntry`
|
|
|
|
The entry in the suggestions database.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface SuggestionsDatabaseEntry {
|
|
/**
|
|
* The suggestion entry id.
|
|
*/
|
|
id: SuggestionId;
|
|
|
|
/**
|
|
* The suggestion entry.
|
|
*/
|
|
suggestion: SuggestionEntry;
|
|
}
|
|
```
|
|
|
|
### `FieldAction`
|
|
|
|
The modifying action on a record field.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type FieldAction = Remove | Set;
|
|
```
|
|
|
|
### `FieldUpdate`
|
|
|
|
An object representing a modification of a field in a record.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface FieldUpdate<T> {
|
|
/**
|
|
* The modifying action.
|
|
*/
|
|
tag: FieldAction;
|
|
|
|
/**
|
|
* The updated value.
|
|
*/
|
|
value?: T;
|
|
}
|
|
```
|
|
|
|
### `SuggestionArgumentUpdate`
|
|
|
|
An operation applied to the suggestion argument.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type SuggestionArgumentUpdate = Add | Remove | Modify;
|
|
|
|
interface Add {
|
|
/**
|
|
* The position of the argument.
|
|
*/
|
|
index: int;
|
|
|
|
/**
|
|
* The argument to add.
|
|
*/
|
|
argument: SuggestionEntryArgument;
|
|
}
|
|
|
|
interface Remove {
|
|
/**
|
|
* The position of the argument.
|
|
*/
|
|
index: int;
|
|
}
|
|
|
|
interface Modify {
|
|
/**
|
|
* The position of the argument.
|
|
*/
|
|
index: int;
|
|
|
|
/**
|
|
* The name to update.
|
|
*/
|
|
name?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The argument type to update.
|
|
*/
|
|
reprType?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The isSuspended flag to update.
|
|
*/
|
|
isSuspended?: FieldUpdate<Boolean>;
|
|
|
|
/**
|
|
* The hasDefault flag to update.
|
|
*/
|
|
hasDefault?: FieldUpdate<Boolean>;
|
|
|
|
/**
|
|
* The default value to update.
|
|
*/
|
|
defaultValue?: FieldUpdate<String>;
|
|
}
|
|
```
|
|
|
|
### `SuggestionsDatabaseUpdate`
|
|
|
|
The update of the suggestions database.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
/**
|
|
* The kind of the suggestions database update.
|
|
*/
|
|
type SuggestionsDatabaseUpdate = Add | Remove | Modify;
|
|
|
|
interface Add {
|
|
/**
|
|
* Suggestion entry id.
|
|
*/
|
|
id: SuggestionId;
|
|
|
|
/**
|
|
* Suggestion entry.
|
|
*/
|
|
suggestion: SuggestionEntry;
|
|
}
|
|
|
|
interface Remove {
|
|
/**
|
|
* Suggestion entry id.
|
|
*/
|
|
id: SuggestionId;
|
|
}
|
|
|
|
interface Modify {
|
|
/**
|
|
* Suggestion entry id.
|
|
*/
|
|
id: SuggestionId;
|
|
|
|
/**
|
|
* The external id to update.
|
|
*/
|
|
externalId?: FieldUpdate<UUID>;
|
|
|
|
/**
|
|
* The list of argument updates.
|
|
*/
|
|
arguments?: SuggestionArgumentUpdate[];
|
|
|
|
/**
|
|
* The module name to update.
|
|
*/
|
|
module?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The self type to update.
|
|
*/
|
|
selfType?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The return type to update.
|
|
*/
|
|
returnType?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The documentation string to update.
|
|
*/
|
|
documentation?: FieldUpdate<String>;
|
|
|
|
/**
|
|
* The scope to update.
|
|
*/
|
|
scope?: FieldUpdate<SuggestionEntryScope>;
|
|
|
|
/**
|
|
* The reexport field to update.
|
|
*/
|
|
reexport?: FieldUpdate<String>;
|
|
}
|
|
```
|
|
|
|
### `SuggestionsOrderDatabaseUpdate`
|
|
|
|
The update of the suggestions order database.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
/**
|
|
* The kind of the suggestions order database update.
|
|
*/
|
|
type SuggestionsOrderDatabaseUpdate = AddOrder | RemoveOrder | ModifyOrder;
|
|
|
|
interface AddOrder {
|
|
entry: SuggestionOrderDatabaseEntry;
|
|
}
|
|
|
|
interface RemoveOrder {
|
|
/**
|
|
* The unique identifier of a suggestion.
|
|
*/
|
|
suggestionId: SuggestionId;
|
|
}
|
|
|
|
interface ModifyOrder {
|
|
/**
|
|
* 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>;
|
|
}
|
|
```
|
|
|
|
### `Export`
|
|
|
|
The info about module re-export.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type Export = Qualified | Unqualified;
|
|
|
|
interface Qualified {
|
|
/**
|
|
* 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.
|
|
*
|
|
* I.e. `X` in `export A.B as X`.
|
|
*/
|
|
alias?: String;
|
|
}
|
|
|
|
interface Unqualified {
|
|
/**
|
|
* The module name that re-exports the given module.
|
|
*/
|
|
module: String;
|
|
}
|
|
```
|
|
|
|
### `File`
|
|
|
|
A representation of a file on disk.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface File {
|
|
name: String; // Includes the file extension
|
|
type: String;
|
|
}
|
|
```
|
|
|
|
### `DirectoryTree`
|
|
|
|
A 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.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface DirectoryTree {
|
|
path: Path;
|
|
name: String;
|
|
files: [FileSystemObject];
|
|
directories: [DirectoryTree];
|
|
}
|
|
```
|
|
|
|
### `FileAttributes`
|
|
|
|
A description of the attributes of a file required by the IDE. These attributes
|
|
may be expanded in future.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
/**
|
|
* 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;
|
|
}
|
|
```
|
|
|
|
### `UTCDateTime`
|
|
|
|
Time in UTC time zone represented as ISO-8601 string
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type UTCDateTime = String;
|
|
```
|
|
|
|
### `FileEventKind`
|
|
|
|
The kind of event being described for a watched file.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type FileEventKind = Added | Removed | Modified;
|
|
```
|
|
|
|
### `Position`
|
|
|
|
A representation of a position in a text file.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
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;
|
|
}
|
|
```
|
|
|
|
```idl
|
|
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;
|
|
}
|
|
```
|
|
|
|
### `Range`
|
|
|
|
A 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
|
|
|
|
```typescript
|
|
{
|
|
start: { line: 0, character: 0},
|
|
end: { line: 0, character: 3}
|
|
}
|
|
```
|
|
|
|
The range of `1` is
|
|
|
|
```typescript
|
|
{
|
|
start: { line: 1, character: 8},
|
|
end: { line: 1, character: 9}
|
|
}
|
|
```
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface Range {
|
|
/**
|
|
* The range's start position (inclusive).
|
|
*/
|
|
start: Position;
|
|
|
|
/**
|
|
* The range's end position (exclusive).
|
|
*/
|
|
end: Position;
|
|
}
|
|
```
|
|
|
|
### `TextEdit`
|
|
|
|
A representation of a change to a text file at a given position.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface TextEdit {
|
|
/** The range of text in a text file. */
|
|
range: Range;
|
|
|
|
/** The change to a text file. */
|
|
text: string;
|
|
}
|
|
```
|
|
|
|
### `DiagnosticType`
|
|
|
|
The type of diagnostic message.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type DiagnosticType = Error | Warning;
|
|
```
|
|
|
|
### `StackTraceElement`
|
|
|
|
The frame of the stack trace. If the error refer to a builtin node, the `path`
|
|
and `location` fields will be empty.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
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 a file.
|
|
*/
|
|
location?: Range;
|
|
}
|
|
```
|
|
|
|
### `Diagnostic`
|
|
|
|
A 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).
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface Diagnostic {
|
|
/**
|
|
* The type of diagnostic message.
|
|
*/
|
|
kind: DiagnosticType;
|
|
|
|
/**
|
|
* The diagnostic message.
|
|
*/
|
|
message: String;
|
|
|
|
/**
|
|
* The location of a file containing the diagnostic.
|
|
*/
|
|
path?: Path;
|
|
|
|
/**
|
|
* The location of the diagnostic object in a file.
|
|
*/
|
|
location?: Range;
|
|
|
|
/**
|
|
* The id of related expression.
|
|
*/
|
|
expressionId?: ExpressionId;
|
|
|
|
/**
|
|
* The stack trace.
|
|
*/
|
|
stack: StackTraceElement[];
|
|
}
|
|
```
|
|
|
|
### `SHA3-224`
|
|
|
|
The `SHA3-224` message digest encoded as a base16 string. For the equivalent
|
|
structure on the binary connection please see [`EnsoDigest`](#ensodigest)
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
type SHA3-224 = String;
|
|
```
|
|
|
|
### `FileEdit`
|
|
|
|
A 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,
|
|
|
|
```python
|
|
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:
|
|
|
|
```haskell
|
|
applyEdits buffer [] = buffer
|
|
applyEdits buffer (first : rest) = applyEdits (applyTextEdit buffer first) rest
|
|
```
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface FileEdit {
|
|
path: Path;
|
|
edits: [TextEdit];
|
|
oldVersion: SHA3-224;
|
|
newVersion: SHA3-224;
|
|
}
|
|
```
|
|
|
|
### `FileContents`
|
|
|
|
A representation of the contents of a file.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
interface FileContents<T> {
|
|
contents: T;
|
|
}
|
|
|
|
class TextFileContents extends FileContents<String> {}
|
|
```
|
|
|
|
### `FileSystemObject`
|
|
|
|
A representation of what kind of type a filesystem object can be.
|
|
|
|
#### Format
|
|
|
|
```typescript
|
|
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;
|
|
}
|
|
```
|
|
|
|
### `WorkspaceEdit`
|
|
|
|
This 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.
|
|
|
|
### `EnsoDigest`
|
|
|
|
A counterpart to [SHA3-224](#sha3-224) for the binary connection, this is a
|
|
standard message digest encoded using FlatBuffers.
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table EnsoDigest {
|
|
bytes : [ubyte] (required);
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- It is an error for the length of the vector `bytes` to not be equal to 28 (224
|
|
/ 8). This is the length of the chosen digest in bytes.
|
|
|
|
### `FileSegment`
|
|
|
|
A representation of a segment of a file for use in the binary protocol.
|
|
|
|
```idl
|
|
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`.
|
|
|
|
### `ContentRoot`
|
|
|
|
A 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.
|
|
|
|
```typescript
|
|
type ContentRoot = Project | FileSystemRoot | Home | Library | Custom;
|
|
```
|
|
|
|
```typescript
|
|
/** 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 of the library 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;
|
|
}
|
|
```
|
|
|
|
### `LibraryEntry`
|
|
|
|
Represents a library available in a resolved edition.
|
|
|
|
```typescript
|
|
interface LibraryEntry {
|
|
namespace: String;
|
|
name: String;
|
|
version: LibraryVersion;
|
|
isCached: Boolean;
|
|
}
|
|
```
|
|
|
|
### `LibraryVersion`
|
|
|
|
Represents a library version, as returned in `LibraryEntry`.
|
|
|
|
```typescript
|
|
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;
|
|
|
|
// URL to the repository that this library will be downloaded from.
|
|
repositoryUrl: String;
|
|
}
|
|
|
|
// A library version that references a locally editable version of the library.
|
|
interface LocalLibraryVersion {}
|
|
```
|
|
|
|
### `Contact`
|
|
|
|
Represents 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.
|
|
|
|
```typescript
|
|
interface Contact {
|
|
name?: String;
|
|
email?: String;
|
|
}
|
|
```
|
|
|
|
### `EditionReference`
|
|
|
|
A 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.
|
|
|
|
```typescript
|
|
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;
|
|
}
|
|
```
|
|
|
|
### `LibraryComponentGroups`
|
|
|
|
The description of component groups provided by the package. Object fields can
|
|
be omitted if the corresponding list is empty.
|
|
|
|
```typescript
|
|
interface LibraryComponentGroups {
|
|
/** The list of component groups provided by the package. */
|
|
newGroups?: LibraryComponentGroup[];
|
|
|
|
/** The list of component groups that this package extends.*/
|
|
extendedGroups?: LibraryComponentGroup[];
|
|
}
|
|
```
|
|
|
|
### `LibraryComponentGroup`
|
|
|
|
The component group provided by a library.
|
|
|
|
```typescript
|
|
interface LibraryComponentGroup {
|
|
/**
|
|
* The fully qualified library name. A string consisting of a namespace and
|
|
* a library name separated by the dot <namespace>.<library name>,
|
|
* i.e. `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;
|
|
|
|
/** The list of components provided by this component group. */
|
|
exports: LibraryComponent[];
|
|
}
|
|
```
|
|
|
|
### `LibraryComponent`
|
|
|
|
A single component of a component group.
|
|
|
|
```typescript
|
|
interface LibraryComponent {
|
|
/** The component name. */
|
|
name: string;
|
|
|
|
/** The component shortcut. */
|
|
shortcut?: string;
|
|
}
|
|
```
|
|
|
|
## Connection Management
|
|
|
|
In order to properly set-up and tear-down the language server connection, we
|
|
need a set of messages to control this process.
|
|
|
|
### `session/initProtocolConnection`
|
|
|
|
This message initialises the connection used to send the textual protocol
|
|
messages. This initialisation is important such that the client identifier can
|
|
be correlated between the textual and data connections.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
clientId: UUID;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
contentRoots: [ContentRoot];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`SessionAlreadyInitialisedError`](#sessionalreadyinitialisederror) to signal
|
|
that session is already initialised.
|
|
- [`ResourcesInitializationError`](#resourcesinitializationerror) to signal
|
|
about the error during the initialization of Language Server resources.
|
|
|
|
### `session/initBinaryConnection`
|
|
|
|
This message initialises the data connection used for transferring binary data
|
|
between engine and clients. This initialisation is important such that the
|
|
client identifier can be correlated between the data and textual connections.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Data
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
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;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
//Indicates an operation has succeeded.
|
|
table Success {}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
## Capability Management
|
|
|
|
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/acquire`
|
|
|
|
This requests that the server grant the specified capability to the requesting
|
|
client.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
method: String;
|
|
registerOptions?: any;
|
|
}
|
|
```
|
|
|
|
The `registerOptions` are determined by the `method`. The method must be listed
|
|
in the section on [capabilities](#capabilities) below.
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
### `capability/release`
|
|
|
|
This requests that the server acknowledge that the client is releasing a given
|
|
capability.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
registration: CapabilityRegistration;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
### `capability/granted`
|
|
|
|
This notifies the client that it has been granted a capability without any
|
|
action on its part.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
registration: CapabilityRegistration;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
### `capability/forceReleased`
|
|
|
|
This notifies the client that a capability has been forcibly removed from its
|
|
capability set.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
registration: CapabilityRegistration;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
## Capabilities
|
|
|
|
The capability management features work with the following capabilities.
|
|
|
|
### `text/canEdit`
|
|
|
|
This capability states that the capability has the ability to perform both
|
|
`text/applyEdit` and `text/save` for the specified file.
|
|
|
|
- **method:** `text/canEdit`
|
|
- **registerOptions:** `{path: Path;}`
|
|
|
|
#### Enables
|
|
|
|
- [`text/applyEdit`](#textapplyedit)
|
|
- [`text/save`](#textsave)
|
|
|
|
#### Disables
|
|
|
|
None
|
|
|
|
### `file/receivesTreeUpdates`
|
|
|
|
This capability states that the client will receive updates for any watched
|
|
content roots in the current project.
|
|
|
|
- **method:** `file/receivesTreeUpdates`
|
|
- **registerOptions:** `{ path: Path; }`
|
|
|
|
#### Enables
|
|
|
|
- [`file/event`](#fileevent)
|
|
|
|
#### Disables
|
|
|
|
None
|
|
|
|
#### Errors
|
|
|
|
[`capability/acquire`](#capabilityacquire):
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`FileNotFound`](#filenotfound) informs that path cannot be found.
|
|
|
|
[`capability/release`](#capabilityrelease):
|
|
|
|
- [`CapabilityNotAcquired`](#capabilitynotacquired) informs that requested
|
|
capability is not acquired.
|
|
|
|
### `executionContext/canModify`
|
|
|
|
This capability states that the client has the ability to modify an execution
|
|
context, including modifying the execution stack, invalidating caches, or
|
|
destroying the context.
|
|
|
|
- **method:** `executionContext/canModify`
|
|
- **registerOptions:** `{ contextId: ContextId; }`
|
|
|
|
#### Enables
|
|
|
|
- [`executionContext/destroy`](#executioncontextdestroy)
|
|
- [`executionContext/recompute`](#executioncontextrecompute)
|
|
- [`executionContext/push`](#executioncontextpush)
|
|
- [`executionContext/pop`](#executioncontextpop)
|
|
- [`executionContext/executeExpression`](#executioncontextexecuteexpression)
|
|
- [`executionContext/attachVisualisation`](#executioncontextattachvisualisation)
|
|
- [`executionContext/modifyVisualisation`](#executioncontextmodifyvisualisation)
|
|
- [`executionContext/detachVisualisation`](#executioncontextdetachvisualisation)
|
|
- [`executionContext/visualisationUpdate`](#executioncontextvisualisationupdate)
|
|
- [`executionContext/visualisationEvaluationFailed`](#executioncontextvisualisationevaluationfailed)
|
|
|
|
#### Disables
|
|
|
|
None
|
|
|
|
### `executionContext/receivesUpdates`
|
|
|
|
This capability states that the client receives expression value updates from a
|
|
given execution context.
|
|
|
|
- **method:** `executionContext/receivesUpdates`
|
|
- **registerOptions:** `{ contextId: ContextId; }`
|
|
|
|
#### Enables
|
|
|
|
- [`executionContext/expressionUpdates`](#executioncontextexpressionupdates)
|
|
- [`executionContext/executionFailed`](#executioncontextexecutionfailed)
|
|
- [`executionContext/executionStatus`](#executioncontextexecutionstatus)
|
|
|
|
#### Disables
|
|
|
|
None
|
|
|
|
### `search/receivesSuggestionsDatabaseUpdates`
|
|
|
|
This capability states that the client receives the search database updates for
|
|
a given execution context.
|
|
|
|
- **method:** `search/receivesSuggestionsDatabaseUpdates`
|
|
- **registerOptions:** `{}`
|
|
|
|
#### Enables
|
|
|
|
- [`search/suggestionsDatabaseUpdate`](#suggestionsdatabaseupdate)
|
|
- [`search/suggestionsOrderDatabaseUpdate`](#suggestionsorderdatabaseupdate)
|
|
|
|
#### Disables
|
|
|
|
None
|
|
|
|
## File Management Operations
|
|
|
|
The language server also provides file operations to the IDE.
|
|
|
|
### `file/write`
|
|
|
|
This requests that the file manager component write to a specified file with the
|
|
specified contents.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
contents: FileContents<T>;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
|
|
### `file/read`
|
|
|
|
This requests that the file manager component reads the contents of a specified
|
|
file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
contents: FileContents<T>;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
|
|
### `file/writeBinary`
|
|
|
|
This requests that the file manager component write to a specified file with the
|
|
binary contents.
|
|
|
|
- **Type:** Request
|
|
- **Connection:** Binary
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
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];
|
|
|
|
}
|
|
|
|
```
|
|
|
|
#### Result
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
//Indicates an operation has succeeded.
|
|
table Success {}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
|
|
### `file/readBinary`
|
|
|
|
This requests that the file manager component reads the binary contents of a
|
|
specified file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Binary
|
|
- **Visibility:** Public
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
//A command reading binary contents from a file.
|
|
table ReadFileCommand {
|
|
|
|
//A path to a file.
|
|
path: Path;
|
|
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
//A reply for a ReadFileCommand.
|
|
table FileContentsReply {
|
|
|
|
//Binary contents.
|
|
contents: [ubyte];
|
|
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
|
|
### `file/writeBytes`
|
|
|
|
This requests that the file manager component writes a set of bytes to the
|
|
specified file at the specified offset.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Binary
|
|
- **Visibility:** Public
|
|
|
|
This method will create a file if no file is present at `path`.
|
|
|
|
- The `overwriteExisting` boolean should be set if `byteOffset` is less than the
|
|
length of the file.
|
|
- The `byteOffset` property is zero-indexed. To append to the file you begin
|
|
writing at index `file.length`.
|
|
- If `byteOffset` is less than the length of the file and `overwriteExisting` is
|
|
set, it will truncate the file to length `byteOffset + bytes.length`.
|
|
- If `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.
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
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);
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table WriteBytesReply {
|
|
// The checksum of the written bytes.
|
|
checksum : EnsoDigest (required);
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- The `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`](#file-checksumbytes).
|
|
|
|
#### Errors
|
|
|
|
- [`CannotOverwrite`](#cannotoverwrite) to signal that an overwrite would be
|
|
necessary to perform the operation but that `overwriteExisting` is not set.
|
|
- [`NotFile`](#notfile) if the provided `segment.path` is not a file.
|
|
|
|
### `file/readBytes`
|
|
|
|
Asks the language server to read the specified number of bytes at the specified
|
|
offset in the file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Binary
|
|
- **Visibility:** Public
|
|
|
|
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).
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table ReadBytesCommand {
|
|
// The segment in a file to read bytes from.
|
|
segment : FileSegment (required);
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```idl
|
|
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:
|
|
|
|
- The `checksum` is of the `bytes` as they have been read from disk.
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotFound`](#filenotfound) if the file at `segment.path` does not exist.
|
|
- [`ReadOutOfBounds`](#readoutofbounds) if `segment.byteOffset` is not present
|
|
in the file at `segment.path`.
|
|
- [`NotFile`](#notfile) if the provided `segment.path` is not a file.
|
|
|
|
### `file/create`
|
|
|
|
This request asks the file manager to create the specified file system object.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
This will fail if the specified object already exists.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
object: FileSystemObject;
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
|
|
### `file/delete`
|
|
|
|
This request asks the file manager to delete the specified file system object.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```
|
|
null
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
- [`FileExists`](#fileexists) informs that file already exists
|
|
|
|
### `file/copy`
|
|
|
|
This request asks the file manager to copy a specified filesystem object to
|
|
another location.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
from: Path;
|
|
to: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
|
|
### `file/move`
|
|
|
|
This request asks the file manager to move a specified filesystem object to
|
|
another location.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
The move should be specified by filesystem events, and such notifications should
|
|
inform the client that the currently edited file has been moved.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
from: Path;
|
|
to: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
- [`FileExists`](#fileexists) informs that target file already exists.
|
|
|
|
### `file/exists`
|
|
|
|
This request asks the file manager to check whether a filesystem object exists
|
|
at the specified path.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
exists: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
|
|
### `file/tree`
|
|
|
|
This request asks the file manager component to generate and provide the
|
|
directory tree starting at a given path.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
depth?: Number;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
tree: DirectoryTree;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that requested path does not exist or
|
|
provided depth argument is <= 0.
|
|
- [`NotDirectory`](#notdirectory) informs that requested path is not a
|
|
directory.
|
|
|
|
### `file/list`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
paths: [FileSystemObject];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that requested path does not exist.
|
|
- [`NotDirectory`](#notdirectory) informs that requested path is not a
|
|
directory.
|
|
|
|
### `file/info`
|
|
|
|
This request gets information about a specified filesystem object.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
This request should work for all kinds of filesystem object.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
attributes: FileAttributes;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`FileNotFound`](#filenotfound) informs that requested path does not exist.
|
|
|
|
### `file/checksum`
|
|
|
|
Requests that the language server provide the checksum of the provided file.
|
|
Only defined when the provided `path` is a file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
It calculates the checksum of the entire file.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface ChecksumRequest {
|
|
// The path to the file to get the checksum for.
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
interface ChecksumResponse {
|
|
// The checksum of the file at `path`.
|
|
checksum : SHA3-224;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotFound`](#filenotfound) if the file at `path` does not exist.
|
|
- [`NotFile`](#notfile) if the provided `path` does not point to a file.
|
|
|
|
### `file/checksumBytes`
|
|
|
|
Requests that the language server provides the checksum of the provided byte
|
|
range.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Binary
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table ChecksumBytesCommand {
|
|
// The segment in a file to checksum.
|
|
segment : FileSegment (required);
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table ChecksumBytesReply {
|
|
// The segment in a file to checksum.
|
|
checksum : EnsoDigest;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotFound`](#filenotfound) if the file at `segment.path` does not exist.
|
|
- [`ReadOutOfBounds`](#readoutofbounds) if `segment.byteOffset` is not present
|
|
in the file at `segment.path`, or if `segment.length` does not fit within the
|
|
file.
|
|
- [`NotFile`](#notfile) if the provided `segment.path` is not a file.
|
|
|
|
### `file/event`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
Events should be sent from server to client for every event observed under one
|
|
of the (possibly multiple) content roots.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
kind: FileEventKind;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `file/rootAdded`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: ContentRoot;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
### `file/rootRemoved`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
id: UUID; // The content root ID
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
TBC
|
|
|
|
## Version Control System Operations
|
|
|
|
The language server has a set of version control operations to keep track of
|
|
changes made to the projects.
|
|
|
|
### `vcs/init`
|
|
|
|
This requests that the VCS manager component initializes version control for the
|
|
project identified by the root directory.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`VCSError`](#vcserror) to signal a generic, unrecoverable VCS error.
|
|
- [`ProjectNotFound`](#projectnotfounderror) to signal that the requested
|
|
project does not exist
|
|
- [`VCSAlreadyPresent`](#vcsalreadyexistserror) to signal that the requested
|
|
project does not exist
|
|
|
|
### `vcs/save`
|
|
|
|
This requests that the VCS manager component record any changes made to the
|
|
project, compared to the last save.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: Path;
|
|
name?: String;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
commitId: String;
|
|
message: String;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`VCSError`](#vcserror) to signal a generic, unrecoverable VCS error.
|
|
- [`ProjectNotFound`](#projectnotfounderror) to signal that the requested
|
|
project does not exist
|
|
- [`VCSNotFound`](#vcsnotfounderror) to signal that the project is not under
|
|
Enso's version control
|
|
|
|
### `vcs/status`
|
|
|
|
This requests that the VCS manager component report the current status of the
|
|
changes made to the project.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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 deleted
|
|
- list of paths to the modified files, if any
|
|
- the metadata of a last save
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
dirty: Boolean;
|
|
changed: [Path];
|
|
lastSave: {
|
|
commitId: String;
|
|
message: String;
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`VCSError`](#vcserror) to signal a generic, unrecoverable VCS error.
|
|
- [`ProjectNotFound`](#projectnotfounderror) to signal that the requested
|
|
project does not exist
|
|
- [`VCSNotFound`](#vcsnotfounderror) to signal that the project is not under
|
|
Enso's version control
|
|
|
|
### `vcs/restore`
|
|
|
|
This requests that the VCS manager component restores the project to a past
|
|
state recorded in Enso's VCS. All unsaved changes will be lost.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: Path;
|
|
commitId?: String
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`VCSError`](#vcserror) to signal a generic, unrecoverable VCS error.
|
|
- [`ProjectNotFound`](#projectnotfounderror) to signal that the requested
|
|
project does not exist
|
|
- [`VCSNotFound`](#vcsnotfounderror) to signal that the project is not under
|
|
Enso's version control
|
|
- [`SaveNotFound`](#savenotfounderror) to signat that the requested save could
|
|
not be identified in the project's version control
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
### `vcs/list`
|
|
|
|
This requests that the VCS manager component returns a list of project's saves.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
root: Path;
|
|
limit?: Number
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
saves: [
|
|
{
|
|
commitId: String;
|
|
message: String;
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`VCSError`](#vcserror) to signal a generic, unrecoverable VCS error.
|
|
- [`ProjectNotFound`](#projectnotfounderror) to signal that the requested
|
|
project does not exist
|
|
- [`VCSNotFound`](#vcsnotfounderror) to signal that the project is not under
|
|
Enso's version control
|
|
|
|
## Text Editing Operations
|
|
|
|
The language server also has a set of text editing operations to ensure that it
|
|
stays in sync with the clients.
|
|
|
|
### `text/openFile`
|
|
|
|
This requests the language server to open the specified file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
If no client has write lock on the opened file, the capability is granted to the
|
|
client that sent the `text/openFile` message.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
writeCapability?: CapabilityRegistration;
|
|
content: String;
|
|
currentVersion: SHA3-224;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
- [`FileNotFound`](#filenotfound) informs that file cannot be found.
|
|
|
|
### `text/openBuffer`
|
|
|
|
This 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`](#textopenfile). If the path does not exist, the command
|
|
creates empty in-memory buffer for the provided path.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
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`](#textopenfile) but does not
|
|
require the file to exist.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
writeCapability?: CapabilityRegistration;
|
|
content: String;
|
|
currentVersion: SHA3-224;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that a user doesn't have
|
|
access to a resource.
|
|
|
|
### `text/closeFile`
|
|
|
|
This requests the language server to close the specified file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
Any pending changes to files will be saved before closing the file.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotOpenedError`](#filenotopenederror) to signal that a file wasn't
|
|
opened.
|
|
|
|
### `text/save`
|
|
|
|
This requests for the language server to save the specified file.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
currentVersion: SHA3 - 224;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotOpenedError`](#filenotopenederror) to signal that the file isn't
|
|
open.
|
|
- [`InvalidVersionError`](#invalidversionerror) to signal that the version
|
|
provided by the client doesn't match the version computed by the server.
|
|
- [`WriteDeniedError`](#writedeniederror) to signal that the client doesn't hold
|
|
write lock for the buffer.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
- [`ContentRootNotFoundError`](#contentrootnotfounderror) to signal that the
|
|
requested content root cannot be found.
|
|
- [`AccessDeniedError`](#accessdeniederror) to signal that the user doesn't have
|
|
access to a resource.
|
|
|
|
### `text/applyEdit`
|
|
|
|
This requests that the server apply a series of edits to the project. These
|
|
edits solely concern text files.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
/** The file edit. */
|
|
edit: FileEdit;
|
|
|
|
/** The flag indicating whether we should re-execute the program after
|
|
* applying the edit. Default value is `true`, to re-execute the program.
|
|
*/
|
|
execute?: boolean;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotOpenedError`](#filenotopenederror) to signal that the file isn't
|
|
open.
|
|
- [`TextEditValidationError`](#texteditvalidationerror) to signal that
|
|
validation has failed for a series of edits.
|
|
- [`InvalidVersionError`](#invalidversionerror) to signal that the version
|
|
provided by the client doesn't match the version computed by the server.
|
|
- [`WriteDeniedError`](#writedeniederror) to signal that the client doesn't hold
|
|
write lock for the buffer.
|
|
|
|
### `text/applyExpressionValue`
|
|
|
|
This 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`](#textapplyedit) 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
This operation may fail if the requesting client does not have permission to
|
|
edit the resources for which edits are sent.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface TextApplyExpressionValue {
|
|
/** The expression id to update. */
|
|
expressionId: ExpressionId;
|
|
|
|
/** The path to a file. */
|
|
path: Path;
|
|
|
|
/** The file edit containing the new expression value. */
|
|
edit: TextEdit;
|
|
|
|
/** The current version of a buffer. */
|
|
oldVersion: SHA3-224;
|
|
|
|
/** The version of a buffer after applying the edit. */
|
|
newVersion: SHA3-224;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileNotOpenedError`](#filenotopenederror) to signal that the file isn't
|
|
open.
|
|
- [`TextEditValidationError`](#texteditvalidationerror) to signal that
|
|
validation has failed for this edit.
|
|
- [`InvalidVersionError`](#invalidversionerror) to signal that the version
|
|
provided by the client doesn't match the version computed by the server.
|
|
- [`WriteDeniedError`](#writedeniederror) to signal that the client doesn't hold
|
|
write lock for the buffer.
|
|
|
|
### `text/didChange`
|
|
|
|
This is a notification sent from the server to the clients to inform them of any
|
|
changes made to files that they have open.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
This notification must _only_ be sent for files that the client has open.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
edits: [FileEdit];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
### `text/autoSave`
|
|
|
|
This is a notification sent from the server to the clients to inform them of any
|
|
successful auto-save action.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
This notification must _only_ be sent for files that the client has open.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
path: Path;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
## Workspace Operations
|
|
|
|
The language server also has a set of operations useful for managing the client
|
|
workspace.
|
|
|
|
### `workspace/projectInfo`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
// 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;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`CannotDecode`](#cannotdecode) if the project configuration cannot be
|
|
decoded.
|
|
- [`FileNotFound`](#filenotfound) if the project configuration cannot be found.
|
|
|
|
## Monitoring
|
|
|
|
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/ping`
|
|
|
|
This request is sent from the supervisor process to the server to check the
|
|
health of the Language Server.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Supervisor -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Private
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `heartbeat/init`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Supervisor -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Private
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
## Refactoring
|
|
|
|
The language server also provides refactoring operations to restructure an
|
|
internal body of code.
|
|
|
|
### `refactoring/renameProject`
|
|
|
|
This request is sent from the project manager to the server to refactor project
|
|
name in an interpreter runtime.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Project Manager -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Private
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
oldName: String;
|
|
newName: String;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
## Execution Management Operations
|
|
|
|
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.
|
|
|
|
### Execution Management Example
|
|
|
|
Given the default project structure.
|
|
|
|
```text
|
|
├── package.yaml
|
|
└── src
|
|
└── Main.enso
|
|
```
|
|
|
|
```bash
|
|
$ 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.
|
|
|
|
### Create Execution Context
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "executionContext/create",
|
|
"id": 0,
|
|
"params": null
|
|
}
|
|
```
|
|
|
|
Return capabilities together with a newly created `ContextId`.
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Push Item
|
|
|
|
Entering the `main` method. First item on the stack should always be an
|
|
`ExplicitCall`.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 0,
|
|
"result": null
|
|
}
|
|
```
|
|
|
|
And a value update, result of the method `foo` call defined on type `Number`.
|
|
|
|
```json
|
|
{
|
|
"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 `LocalCall`s.
|
|
|
|
```json
|
|
{
|
|
"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 reponse.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 0,
|
|
"result": null
|
|
}
|
|
```
|
|
|
|
And update of some value inside the function `foo`.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pop Item
|
|
|
|
```json
|
|
{
|
|
"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/create`
|
|
|
|
Sent from the client to the server to create a new execution context. Return
|
|
capabilities [`executionContext/canModify`](#executioncontextcanmodify) and
|
|
[`executionContext/receivesUpdates`](#executioncontextreceivesupdates). 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId?: ContextId
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
canModify: CapabilityRegistration;
|
|
receivesUpdates: CapabilityRegistration;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `executionContext/destroy`
|
|
|
|
Sent from the client to the server destroy an execution context and free its
|
|
resources.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`ContextNotFoundError`](#contextnotfounderror) when context can not be found
|
|
by provided id.
|
|
|
|
### `executionContext/fork`
|
|
|
|
Sent 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`](#executioncontextcanmodify)
|
|
and [`executionContext/receivesUpdates`](#executioncontextreceivesupdates).
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
canModify: CapabilityRegistration;
|
|
receivesUpdates: CapabilityRegistration;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
No known errors.
|
|
|
|
### `executionContext/push`
|
|
|
|
Sent 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
stackItem: StackItem;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`StackItemNotFoundError`](#stackitemnotfounderror) when the request stack
|
|
item could not be found.
|
|
- [`InvalidStackItemError`](#invalidstackitemerror) when pushing `LocalCall` on
|
|
top of the empty stack, or pushing `ExplicitCall` on top of non-empty stack.
|
|
|
|
### `executionContext/pop`
|
|
|
|
Sent from the client to the server move the execution context up the stack,
|
|
corresponding to the client clicking out of the current breadcrumb.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`EmptyStackError`](#emptystackerror) when the user tries to pop an empty
|
|
stack.
|
|
|
|
### `executionContext/recompute`
|
|
|
|
Sent from the client to the server to force recomputation of current position.
|
|
May include a list of expressions for which caches should be invalidated.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
invalidatedExpressions?: "all" | [ExpressionId]
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`EmptyStackError`](#emptystackerror) when the user tries to recompute an
|
|
empty stack.
|
|
|
|
### `executionContext/getComponentGroups`
|
|
|
|
Sent 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`](#executioncontextexecutioncomplete)
|
|
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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
componentGroups: LibraryComponentGroup[];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when context with the provided id
|
|
does not exist.
|
|
|
|
### `executionContext/expressionUpdates`
|
|
|
|
Sent 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.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
contextId: ContextId;
|
|
updates: [ExpressionUpdate];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `executionContext/executionFailed`
|
|
|
|
Sent from the server to the client to inform about a critical failure when
|
|
attempting to execute a context.
|
|
|
|
When the [`executionContext/executionStatus`](#executioncontextexecutionstatus)
|
|
notifies about potential problems in the code found by compiler, or the errors
|
|
during runtime, this message signals about the errors in the logic or the
|
|
implementation. It 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`](#executioncontextpush) command.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
/**
|
|
* The identifier of the execution context.
|
|
*/
|
|
contextId: ContextId;
|
|
|
|
/**
|
|
* The error message.
|
|
*/
|
|
message: String;
|
|
|
|
/**
|
|
* The location of a file producing the error.
|
|
*/
|
|
path?: Path;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `executionContext/executionComplete`
|
|
|
|
Sent from the server to the client to inform about the successful execution of a
|
|
context.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
/** The identifier of the execution context. */
|
|
contextId: ContextId;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `executionContext/executionStatus`
|
|
|
|
Sent from the server to the client to inform about a status of execution.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
/**
|
|
* The identifier of the execution context.
|
|
*/
|
|
contextId: ContextId;
|
|
|
|
/**
|
|
* The list of encountered problems.
|
|
*/
|
|
diagnostics: Diagnostic[];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `executionContext/executeExpression`
|
|
|
|
This message allows the client to execute an arbitrary expression on a given
|
|
node. It behaves like oneshot
|
|
[`executionContext/attachVisualisation`](#executioncontextattachvisualisation)
|
|
visualisation request, meaning that the visualisation expression will be
|
|
executed only once.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface ExecuteExpressionRequest {
|
|
visualisationId: UUID;
|
|
expressionId: UUID;
|
|
visualisationConfig: VisualisationConfiguration;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`ContextNotFoundError`](#contextnotfounderror) when context can not be found
|
|
by provided id.
|
|
- [`ModuleNotFoundError`](#modulenotfounderror) to signal that the module with
|
|
the visualisation cannot be found.
|
|
- [`VisualisationExpressionError`](#visualisationexpressionerror) to signal that
|
|
the expression specified in the `VisualisationConfiguration` cannot be
|
|
evaluated.
|
|
|
|
### `executionContext/attachVisualisation`
|
|
|
|
This message allows the client to attach a visualisation, potentially
|
|
preprocessed by some arbitrary Enso code, to a given node in the program.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface AttachVisualisationRequest {
|
|
visualisationId: UUID;
|
|
expressionId: UUID;
|
|
visualisationConfig: VisualisationConfiguration;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`ContextNotFoundError`](#contextnotfounderror) when context can not be found
|
|
by provided id.
|
|
- [`ModuleNotFoundError`](#modulenotfounderror) to signal that the module with
|
|
the visualisation cannot be found.
|
|
- [`VisualisationExpressionError`](#visualisationexpressionerror) to signal that
|
|
the expression specified in the `VisualisationConfiguration` cannot be
|
|
evaluated.
|
|
|
|
### `executionContext/detachVisualisation`
|
|
|
|
This message allows a client to detach a visualisation from the executing code.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface DetachVisualisationRequest {
|
|
executionContextId: UUID;
|
|
visualisationId: UUID;
|
|
expressionId: UUID;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`ContextNotFoundError`](#contextnotfounderror) when context can not be found
|
|
by provided id.
|
|
- [`VisualisationNotFoundError`](#visualisationnotfounderror) when a
|
|
visualisation can not be found.
|
|
|
|
### `executionContext/modifyVisualisation`
|
|
|
|
This message allows a client to modify the configuration for an existing
|
|
visualisation.
|
|
|
|
A successful response means that the new visualization configuration has been
|
|
applied. In case of an error response, the visualization state does not change.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface ModifyVisualisationRequest {
|
|
visualisationId: UUID;
|
|
visualisationConfig: VisualisationConfiguration;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`AccessDeniedError`](#accessdeniederror) when the user does not hold the
|
|
`executionContext/canModify` capability for this context.
|
|
- [`ContextNotFoundError`](#contextnotfounderror) when context can not be found
|
|
by provided id.
|
|
- [`ModuleNotFoundError`](#modulenotfounderror) to signal that the module with
|
|
the visualisation cannot be found.
|
|
- [`VisualisationExpressionError`](#visualisationexpressionerror) to signal that
|
|
the expression specified in the `VisualisationConfiguration` cannot be
|
|
evaluated.
|
|
- [`VisualisationNotFoundError`](#visualisationnotfounderror) when a
|
|
visualisation can not be found.
|
|
|
|
### `executionContext/visualisationUpdate`
|
|
|
|
This message is responsible for providing a visualisation data update to the
|
|
client.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Data
|
|
- **Visibility:** Public
|
|
|
|
The `visualisationData` 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.
|
|
|
|
#### Parameters
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
//A visualisation context identifying a concrete visualisation.
|
|
table VisualisationContext {
|
|
|
|
//A visualisation identifier.
|
|
visualisationId: EnsoUUID (required);
|
|
|
|
//A context identifier.
|
|
contextId: EnsoUUID (required);
|
|
|
|
//An expression identifier.
|
|
expressionId: EnsoUUID (required);
|
|
|
|
}
|
|
|
|
//An event signaling visualisation update.
|
|
table VisualisationUpdate {
|
|
|
|
//A visualisation context identifying a concrete visualisation.
|
|
visualisationContext: VisualisationContext (required);
|
|
|
|
//A visualisation data.
|
|
data: [ubyte] (required);
|
|
|
|
}
|
|
|
|
root_type VisualisationUpdate;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `executionContext/visualisationEvaluationFailed`
|
|
|
|
Signals that an evaluation of a visualisation expression on the computed value
|
|
has failed.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
interface VisualisationEvaluationFailed {
|
|
/**
|
|
* An execution context identifier.
|
|
*/
|
|
contextId: ContextId;
|
|
|
|
/**
|
|
* A visualisation identifier.
|
|
*/
|
|
visualisationId: UUID;
|
|
|
|
/**
|
|
* An identifier of a visualised expression.
|
|
*/
|
|
expressionId: UUID;
|
|
|
|
/**
|
|
* An error message.
|
|
*/
|
|
message: string;
|
|
|
|
/**
|
|
* Detailed information about the error.
|
|
*/
|
|
diagnostic?: Diagnostic;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
## Search Operations
|
|
|
|
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`](#suggestionentry) values.
|
|
|
|
### Suggestions Database Example
|
|
|
|
The following code snippet shows examples of the database entries.
|
|
|
|
```ruby
|
|
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
|
|
```
|
|
|
|
#### MyType
|
|
|
|
```typescript
|
|
<Constructor>{
|
|
name: "MyType",
|
|
arguments: [],
|
|
returnType: "MyType",
|
|
};
|
|
```
|
|
|
|
#### Maybe.Nothing
|
|
|
|
```typescript
|
|
<Constructor>{
|
|
name: "Nothing",
|
|
arguments: [],
|
|
returnType: "Maybe",
|
|
};
|
|
```
|
|
|
|
#### Maybe.Just
|
|
|
|
```typescript
|
|
<Constructor>{
|
|
name: "Just",
|
|
arguments: [
|
|
{
|
|
name: "a",
|
|
type: "Any",
|
|
isSuspended: false,
|
|
hasDefault: false,
|
|
},
|
|
],
|
|
returnType: "Maybe",
|
|
};
|
|
```
|
|
|
|
#### Maybe.is_just
|
|
|
|
```typescript
|
|
<Method>{
|
|
name: "is_just",
|
|
arguments: [],
|
|
selfType: "Maybe",
|
|
returnType: "Bool",
|
|
};
|
|
```
|
|
|
|
#### foo
|
|
|
|
```typescript
|
|
<Function>{
|
|
name: "foo",
|
|
arguments: [
|
|
{
|
|
name: "x",
|
|
type: "Number",
|
|
isSuspended: false,
|
|
hasDefault: false,
|
|
},
|
|
],
|
|
returnType: "Bool",
|
|
};
|
|
```
|
|
|
|
#### Number.baz
|
|
|
|
```typescript
|
|
<Method>{
|
|
name: "baz",
|
|
arguments: [
|
|
{
|
|
name: "x",
|
|
type: "Number",
|
|
isSuspended: false,
|
|
hasDefault: false,
|
|
},
|
|
],
|
|
selfType: "Number",
|
|
returnType: "Number",
|
|
};
|
|
```
|
|
|
|
#### Local x
|
|
|
|
```typescript
|
|
<Local>{
|
|
name: "x",
|
|
returnType: "Number",
|
|
};
|
|
```
|
|
|
|
#### Local y
|
|
|
|
```typescript
|
|
<Local>{
|
|
name: "y",
|
|
returnType: "Number",
|
|
};
|
|
```
|
|
|
|
### `search/getSuggestionsDatabase`
|
|
|
|
Sent from client to the server to receive the full suggestions database.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
// The list of suggestions database entries
|
|
entries: [SuggestionsDatabaseEntry];
|
|
// The version of received suggestions database
|
|
currentVersion: number;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror) an error accessing the
|
|
suggestions database
|
|
- [`ProjectNotFoundError`](#projectnotfounderror) project is not found in the
|
|
root directory
|
|
|
|
### `search/invalidateSuggestionsDatabase`
|
|
|
|
Sent from client to the server to clean the suggestions database resetting the
|
|
version.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror) an error accessing the
|
|
suggestions database
|
|
|
|
### `search/getSuggestionsDatabaseVersion`
|
|
|
|
Sent from client to the server to receive the current version of the suggestions
|
|
database.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
// The version of the suggestions database
|
|
currentVersion: number;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror) an error accessing the
|
|
suggestions database
|
|
- [`ProjectNotFoundError`](#projectnotfounderror) project is not found in the
|
|
root directory
|
|
|
|
### `search/suggestionsDatabaseUpdate`
|
|
|
|
Sent from server to the client to inform abouth the change in the suggestions
|
|
database.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
updates: [SuggestionsDatabaseUpdate];
|
|
currentVersion: number;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `search/suggestionsOrderDatabaseUpdate`
|
|
|
|
Sent from server to the client to inform abouth the change in the suggestions
|
|
order database.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
updates: [SuggestionsOrderDatabaseUpdate];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
None
|
|
|
|
### `search/completion`
|
|
|
|
Sent from client to the server to receive the autocomplete suggestion.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
// 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];
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
The identifiers in `results` are guaranteed to be ordered by the specificity of
|
|
the type match.
|
|
|
|
```typescript
|
|
{
|
|
results: [SuggestionId];
|
|
currentVersion: number;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror) an error accessing the
|
|
suggestions database
|
|
- [`ProjectNotFoundError`](#projectnotfounderror) project is not found in the
|
|
root directory
|
|
- [`ModuleNameNotResolvedError`](#modulenamenotresolvederror) the module name
|
|
cannot be extracted from the provided file path parameter
|
|
|
|
#### Errors
|
|
|
|
- [`SuggestionsDatabaseError`](#suggestionsdatabaseerror) an error accessing the
|
|
suggestions database
|
|
- [`SuggestionNotFoundError`](#suggestionnotfounderror) the requested suggestion
|
|
was not found in the suggestions database
|
|
|
|
## Input/Output Operations
|
|
|
|
The 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/redirectStandardOutput`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `io/suppressStandardOutput`
|
|
|
|
This message allows a client to suppress the redirection of the standard output.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `io/standardOutputAppended`
|
|
|
|
Sent from the server to the client to inform that new output data are available
|
|
for the standard output.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
output: String;
|
|
}
|
|
```
|
|
|
|
### `io/redirectStandardError`
|
|
|
|
This 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.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `io/suppressStandardError`
|
|
|
|
This message allows a client to suppress the redirection of the standard error.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `io/standardErrorAppended`
|
|
|
|
Sent from the server to the client to inform that new output data are available
|
|
for the standard error.
|
|
|
|
- **Type:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
output: String;
|
|
}
|
|
```
|
|
|
|
### `io/feedStandardInput`
|
|
|
|
This message allows a client to feed the standard input of Enso programs.
|
|
|
|
- **Type:** Request
|
|
- **Direction:** Client -> Server
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
input: String;
|
|
isLineTerminated: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
N/A
|
|
|
|
### `io/waitingForStandardInput`
|
|
|
|
Sent 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:** Notification
|
|
- **Direction:** Server -> Client
|
|
- **Connection:** Protocol
|
|
- **Visibility:** Public
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
## Library-Related Operations
|
|
|
|
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/listAvailable`
|
|
|
|
Lists 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 `update` was `true` but 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
update: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
editionNames: [String];
|
|
}
|
|
```
|
|
|
|
### `editions/resolve`
|
|
|
|
Resolves 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
edition: EditionReference;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
engineVersion: String;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
|
edition, or some edition referenced in the ancestors of the edition being
|
|
resolved, could not be found.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `editions/getProjectSettings`
|
|
|
|
Returns 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
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/setProjectParentEdition`
|
|
|
|
Sets 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`.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
newEditionName: String;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
needsRestart?: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
|
edition could not be found.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `editions/setProjectLocalLibrariesPreference`
|
|
|
|
Sets 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`.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
preferLocalLibraries: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
needsRestart?: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `editions/listDefinedLibraries`
|
|
|
|
Lists 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`](#librarylistlocal) instead.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
edition: EditionReference;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
availableLibraries: [LibraryEntry];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
|
edition, or an edition referenced in one of its parents, could not be found.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `editions/listDefinedComponents`
|
|
|
|
Lists all the component groups defined in an edition.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
edition: EditionReference;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
availableComponents: LibraryComponentGroup[];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`EditionNotFoundError`](#editionnotfounderror) indicates that the requested
|
|
edition, or an edition referenced in one of its parents, could not be found.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/listLocal`
|
|
|
|
Lists all local libraries available in the system.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
{
|
|
localLibraries: [LibraryEntry];
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/create`
|
|
|
|
Creates 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`](#filerootadded) notification.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
authors: [Contact];
|
|
maintainers: [Contact];
|
|
license: String;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`InvalidLibraryName`](#invalidlibraryname) to signal that the selected
|
|
library name is not valid.
|
|
- [`LibraryAlreadyExists`](#libraryalreadyexists) to signal that a library with
|
|
the given namespace and name already exists.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/getMetadata`
|
|
|
|
Gets 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
version: LibraryVersion;
|
|
}
|
|
```
|
|
|
|
#### Results
|
|
|
|
```typescript
|
|
{
|
|
description?: String;
|
|
tagLine?: String;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
|
with the given name does not exist on the local libraries path.
|
|
- [`InvalidSemverVersion`](#invalidsemverversion) to signal that the provided
|
|
version string is not a valid semver version.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/setMetadata`
|
|
|
|
Sets 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).
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
description?: String;
|
|
tagLine?: String;
|
|
}
|
|
```
|
|
|
|
#### Results
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
|
with the given name does not exist on the local libraries path.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/getPackage`
|
|
|
|
Gets 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
version: LibraryVersion;
|
|
}
|
|
```
|
|
|
|
#### Results
|
|
|
|
```typescript
|
|
{
|
|
license?: String;
|
|
componentGroups?: LibraryComponentGroups;
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
|
with the given name does not exist on the local libraries path.
|
|
- [`InvalidSemverVersion`](#invalidsemverversion) to signal that the provided
|
|
version string is not a valid semver version.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/publish`
|
|
|
|
Publishes 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`](#librarysetmetadata). If it was not set, the publish
|
|
operation will still proceed, but that metadata will be missing.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
authToken: String;
|
|
uploadUrl: String;
|
|
|
|
bumpVersionAfterPublish?: Boolean;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`LocalLibraryNotFound`](#locallibrarynotfound) to signal that a local library
|
|
with the given name does not exist on the local libraries path.
|
|
- [`LibraryPublishError`](#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`](#libraryrepositoryauthenticationerror)
|
|
to signal an authentication failure.
|
|
- [`LibraryUploadError`](#libraryuploaderror) to signal that the upload
|
|
operation has failed, for network-related reasons.
|
|
- [`FileSystemError`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
### `library/preinstall`
|
|
|
|
Ensures 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.
|
|
|
|
#### Parameters
|
|
|
|
```typescript
|
|
{
|
|
namespace: String;
|
|
name: String;
|
|
}
|
|
```
|
|
|
|
#### Result
|
|
|
|
```typescript
|
|
null;
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- [`LibraryNotResolved`](#librarynotresolved) to signal that the requested
|
|
library or one of its dependencies could not be resolved.
|
|
- [`DependencyDiscoveryError`](#dependencydiscoveryerror) to signal that
|
|
dependencies of the library could not be established.
|
|
- [`LibraryDownloadError`](#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`](#filesystemerror) to signal a generic, unrecoverable
|
|
file-system error.
|
|
|
|
## Errors
|
|
|
|
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.
|
|
|
|
### `Error`
|
|
|
|
An error container for the binary connection that contains a code, message and
|
|
payload.
|
|
|
|
```idl
|
|
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:
|
|
|
|
- The union `ErrorPayload` will be extended with additional payloads as
|
|
necessary.
|
|
- All textual-protocol errors can be represented using this structure.
|
|
|
|
### `AccessDeniedError`
|
|
|
|
It signals that a user doesn't have access to a resource.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 100,
|
|
"message" : "Access denied"
|
|
}
|
|
```
|
|
|
|
### `FileSystemError`
|
|
|
|
This error signals generic file system errors.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1000,
|
|
"message" : String
|
|
}
|
|
```
|
|
|
|
### `ContentRootNotFoundError`
|
|
|
|
The error informs that the requested content root cannot be found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1001,
|
|
"message" : "Content root not found"
|
|
}
|
|
```
|
|
|
|
### `FileNotFound`
|
|
|
|
It signals that requested file doesn't exist.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1003,
|
|
"message" : "File not found"
|
|
}
|
|
```
|
|
|
|
### `FileExists`
|
|
|
|
It signals that file already exists.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1004,
|
|
"message" : "File already exists"
|
|
}
|
|
```
|
|
|
|
### `OperationTimeoutError`
|
|
|
|
It signals that IO operation timed out.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1005,
|
|
"message" : "IO operation timeout"
|
|
}
|
|
```
|
|
|
|
### `NotDirectory`
|
|
|
|
It signals that provided path is not a directory.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1006,
|
|
"message" : "Path is not a directory"
|
|
}
|
|
```
|
|
|
|
### `NotFile`
|
|
|
|
It signals that the provided path is not a file.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1007,
|
|
"message" : "Path is not a file"
|
|
}
|
|
```
|
|
|
|
### `CannotOverwrite`
|
|
|
|
Signals that a streaming file write cannot overwrite a portion of the requested
|
|
file.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1008,
|
|
"message" : "Cannot overwrite the file without `overwriteExisting` set"
|
|
}
|
|
```
|
|
|
|
### `ReadOutOfBounds`
|
|
|
|
Signals that the requested file read was out of bounds for the file's size.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1009
|
|
"message" : "Read is out of bounds for the file"
|
|
"payload" : {
|
|
"fileLength" : 0
|
|
}
|
|
}
|
|
```
|
|
|
|
### `CannotDecode`
|
|
|
|
Signals that the project configuration cannot be decoded.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 1010
|
|
"message" : "Cannot decode the project configuration"
|
|
}
|
|
```
|
|
|
|
```idl
|
|
namespace org.enso.languageserver.protocol.binary;
|
|
|
|
table ReadOutOfBoundsError {
|
|
// The actual length of the file.
|
|
fileLength : ulong (required);
|
|
}
|
|
```
|
|
|
|
### `StackItemNotFoundError`
|
|
|
|
It signals that provided stack item was not found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2001,
|
|
"message" : "Stack item not found"
|
|
}
|
|
|
|
```
|
|
|
|
### `ContextNotFoundError`
|
|
|
|
It signals that provided context was not found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2002,
|
|
"message" : "Context not found"
|
|
}
|
|
```
|
|
|
|
### `EmptyStackError`
|
|
|
|
It signals that stack is empty.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2003,
|
|
"message" : "Stack is empty"
|
|
}
|
|
```
|
|
|
|
### `InvalidStackItemError`
|
|
|
|
It signals that stack is invalid in this context.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2004,
|
|
"message" : "Invalid stack item"
|
|
}
|
|
```
|
|
|
|
### `ModuleNotFoundError`
|
|
|
|
It signals that the given module cannot be found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2005,
|
|
"message" : "Module not found [Foo.Bar.Baz]"
|
|
}
|
|
```
|
|
|
|
### `VisualisationNotFoundError`
|
|
|
|
It signals that the visualisation cannot be found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2006,
|
|
"message" : "Visualisation not found"
|
|
}
|
|
```
|
|
|
|
### `VisualisationExpressionError`
|
|
|
|
It signals that the expression specified in the `VisualisationConfiguration`
|
|
cannot be evaluated. The error contains an optional `data` field of type
|
|
[`Diagnostic`](#diagnostic) providing error details.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 2007,
|
|
"message" : "Evaluation of the visualisation 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" : []
|
|
}
|
|
}
|
|
```
|
|
|
|
### `FileNotOpenedError`
|
|
|
|
Signals that a file wasn't opened.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 3001,
|
|
"message" : "File not opened"
|
|
}
|
|
```
|
|
|
|
### `TextEditValidationError`
|
|
|
|
Signals that validation has failed for a series of edits.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 3002,
|
|
"message" : "The start position is after the end position"
|
|
}
|
|
```
|
|
|
|
### `InvalidVersionError`
|
|
|
|
Signals that version provided by a client doesn't match to the version computed
|
|
by the server.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 3003,
|
|
"message" : "Invalid version [client version: ade2967cab172183d1a67ea40cb8e92e23218764bc9934c3795fcea5, server version: 7602967cab172183d1a67ea40cb8e92e23218764bc9934c3795fcea5]"
|
|
}
|
|
```
|
|
|
|
### `WriteDeniedError`
|
|
|
|
Signals that the client doesn't hold write lock to the buffer.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 3004,
|
|
"message" : "Write denied"
|
|
}
|
|
```
|
|
|
|
### `CapabilityNotAcquired`
|
|
|
|
Signals that requested capability is not acquired.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 5001,
|
|
"message" : "Capability not acquired"
|
|
}
|
|
```
|
|
|
|
### `SessionNotInitialisedError`
|
|
|
|
Signals that requested cannot be proccessed, beacuse session is not initialised.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 6001,
|
|
"message" : "Session not initialised"
|
|
}
|
|
```
|
|
|
|
### `SessionAlreadyInitialisedError`
|
|
|
|
Signals that session is already initialised.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 6002,
|
|
"message" : "Session already initialised"
|
|
}
|
|
```
|
|
|
|
### `ResourcesInitializationError`
|
|
|
|
Signals about the failure in the Language Server initialization process.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 6003,
|
|
"message" : "Failed to initialize the Language Server resources"
|
|
}
|
|
```
|
|
|
|
### `SuggestionsDatabaseError`
|
|
|
|
Signals about an error accessing the suggestions database.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 7001,
|
|
"message" : "Suggestions database error"
|
|
}
|
|
```
|
|
|
|
### `ProjectNotFoundError`
|
|
|
|
Signals that the project not found in the root directory.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 7002,
|
|
"message" : "Project not found in the root directory"
|
|
}
|
|
```
|
|
|
|
### `ModuleNameNotResolvedError`
|
|
|
|
Signals that the module name can not be resolved for the given file.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 7003,
|
|
"message" : "Module name can't be resolved for the given file"
|
|
}
|
|
```
|
|
|
|
### `SuggestionNotFoundError`
|
|
|
|
Signals that the requested suggestion was not found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 7004,
|
|
"message" : "Requested suggestion was not found"
|
|
}
|
|
```
|
|
|
|
### `EditionNotFoundError`
|
|
|
|
Signals that an edition could not be found.
|
|
|
|
Its payload includes the name of the edition that could not be found.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8001,
|
|
"message" : "Edition [<name>] could not be found.",
|
|
"payload" : {
|
|
"editionName": "<name>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### `LibraryAlreadyExists`
|
|
|
|
Signals that a local library with the specified namespace and name combination
|
|
already exists, so it cannot be created again.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8002,
|
|
"message" : "Library [<namespace>.<name>] already exists."
|
|
}
|
|
```
|
|
|
|
### `LibraryRepositoryAuthenticationError`
|
|
|
|
Signals that authentication to the library repository was declined.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8003,
|
|
"message" : "Authentication failed: [message]"
|
|
}
|
|
```
|
|
|
|
### `LibraryPublishError`
|
|
|
|
Signals that a request to the library repository failed.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8004,
|
|
"message" : "Could not publish the library: [message]"
|
|
}
|
|
```
|
|
|
|
### `LibraryUploadError`
|
|
|
|
Signals that uploading the library failed for network-related reasons.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8005,
|
|
"message" : "Could not upload the library: [message]"
|
|
}
|
|
```
|
|
|
|
### `LibraryDownloadError`
|
|
|
|
Signals that downloading the library failed for network-related reasons or that
|
|
it was not available in the repository.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8006,
|
|
"message" : "Could not download the library: [message]",
|
|
"payload" : {
|
|
"namespace" : "<namespace>",
|
|
"name" : "<name>",
|
|
"version": "<version>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### `LocalLibraryNotFound`
|
|
|
|
Signals that a local library with the specified namespace and name combination
|
|
was not found on the local libraries path.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8007,
|
|
"message" : "Local library [<namespace>.<name>] has not been found."
|
|
}
|
|
```
|
|
|
|
### `LibraryNotResolved`
|
|
|
|
Signals 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.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8008,
|
|
"message" : "Could not resolve [<namespace>.<name>].",
|
|
"payload" : {
|
|
"namespace" : "<namespace>",
|
|
"name" : "<name>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### `InvalidLibraryName`
|
|
|
|
Signals 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`.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8009,
|
|
"message" : "[<name>] is not a valid name: <reason>.",
|
|
"payload" : {
|
|
"suggestedName" : "<fixed-name>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### `DependencyDiscoveryError`
|
|
|
|
Signals that the library preinstall endpoint could not properly find
|
|
dependencies of the requested library.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8010,
|
|
"message" : "Error occurred while discovering dependencies: <reason>."
|
|
}
|
|
```
|
|
|
|
### `InvalidSemverVersion`
|
|
|
|
Signals that the provided version string is not a valid semver version. The
|
|
message contains the invalid version in the payload.
|
|
|
|
```typescript
|
|
"error" : {
|
|
"code" : 8011,
|
|
"message" : "[<invalid-version>] is not a valid semver version.",
|
|
"payload" : {
|
|
"version" : "<invalid-version>"
|
|
}
|
|
}
|
|
```
|