lsp-types
Haskell library for the Microsoft Language Server Protocol, data types
https://github.com/haskell/lsp
Version on this page: | 2.2.0.0@rev:1 |
LTS Haskell 22.33: | 2.1.1.0 |
Stackage Nightly 2024-09-07: | 2.3.0.0 |
Latest on Hackage: | 2.3.0.0 |
lsp-types-2.2.0.0@sha256:2f049a7e1a17cae50e9d25dae207669e9a1a1ba306a818d9614a46c40b063f17,34860
Module documentation for 2.2.0.0
- Data
- Language
- Language.LSP
- Language.LSP.Protocol
- Language.LSP
lsp-types
Haskell library for the data types for Microsoft Language Server Protocol
It is part of the lsp family of packages, along with lsp and lsp-test
Updating the generated code
To update the generated code, run cabal run generator
from the lsp-types
directory.
Useful links
- https://github.com/haskell/lsp
- https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md
Other resource
See #haskell-language-server on IRC freenode
Changes
Revision history for lsp-types
2.2.0.0 – 2024-04-29
- Update the metamodel. This results in a number of breaking changes to the generated code, mostly replacing anonymous structs with named ones.
2.1.1.0 – 2024-02-24
- Require aeson 2
- Accept
null
in place of a missing field, a common mistake in spec compliance. - Arbitrary instances for everything now exist and are exported via the new
lsp-types-quickcheck
library
2.1.0.0 – 2023-11-13
- Add
dynamicRegistrationSupported
toCapabilities
. - Fully update
fullCaps
for recent spec versions. - Support GHC 9.8, drop checked support for GHC 8.10
2.0.2.0 – 2023-08-24
- Add
Language.LSP.Protocol.Utils.Misc.prettyJSON :: Value -> Doc ann
for prettyprinting JSON, andViaJSON
as a deriving-via newtype wrapper for it. - Generate
Pretty
instances for all LSP types usingViaJSON
.
2.0.1.1 – 2023-08-08
- Fix parsing of notifications with missing params
2.0.1.0 – 2023-07-14
- Removed deprecation pragmas from fields, as these cannot currently be avoided.
- Added
isOptionalMethod
, that checks whether a method is optional according to the spec.
2.0.0.1 – 2023-06-16
- Fixed missing
extra-source-files
formetamodel.json
.
2.0.0.0 – 2023-06-14
- Breaking change: major restructure to generate types and methods from the LSP metamodel.
- Full support for version 3.17 of the LSP specification, many accuracy fixes
- Generated types follow the spec very closely, e.g. using anonymous types, using
a |? Null
instead ofMaybe a
- Anonymous record types in the spec are now represented using
row-types
- Many constructors are now prefixed with their type names
- Documentation from the spec is transferred
- Three top level modules:
Types
(main protocol types),Message
(messages and methods),Capabilities
(capabilities)
- New typeclasses for handling LSP enumerations:
LspEnum
andLspOpenEnum
1.6.0.1 – 2023-12-02
- Add
LANGUAGE DuplicateRecordFields
to facilitate building with GHC 9.8
1.6.0.0 – 2022-09-13
- Add
isSubRangeOf
andpositionInRange
helper functions - Add
ServerCancelled
,RequestFailed
andErrorCodeCustom
server error types - Fix “workspace/semanticTokens/refresh” to be a server method instead of a client method
- Use a packed representation for
NormalizedFilePath
- Add conversions from
OsPath
toNormalizedFilePath
inLanguage.LSP.Types.Uri.OsPath
when using new enoughfilepath
1.5.0.0 – 2022-06-20
- VFS module moved from
lsp-types
tolsp
, as it relates to the actual implementation of a LSP server.
1.4.0.1 – 2022-01-20
- Fix result type of selection range requests.
1.4.0.0 – 2021-12-28
- Aeson 2 compatibility (#360) (@michaelpj)
- Reduced dependency footprint (#383, #384) (@Bodigrim)
- Use appropriate number types (#366) (@michaelpj)
- Fix for #374 (#376) (@pepeiborra)
- Fix virtual file name adding .hs extension (#364) (@heitor-lassarote, @jneira)
- Fix the Semigroup instance for MarkupContent (#361) (@michaelpj)
- Various improvements to spec conformance (@michaelpj)
1.3.0.1 – 2021-08-06
- Rollback NFP interning (#344) (@pepeiborra)
1.3.0.0 – 2021-07-31
- Intern NormalizedFilePaths (#340) (@pepeiborra)
1.2.0.1 – unpublished
- Add compatibility with GHC 9.2 (#345) (@fendor)
- Fix missing lenses (@michaelpj)
- Semantic tokens support (@michaelpj)
- Fix GHC 9 build (@anka-213)
- Add call hierarchy support (@July541)
- Do not crash on workspace/didChangeConfiguration (#321) (@strager)
- Improve error messages on JSON decode failures (#320) (@strager)
1.2.0.0 – 2021-03-28
- Prevent crashing when optional fields are missing (@anka-213)
- Use StrictData (@wz1000)
- Add MarkupContent in SignatureHelp types (@michaelpj)
- Add activeParameter support in SignatureInformation (@michaelpj)
- Add label offset support in SignatureHelp (@michaelpj)
- Add some documentation comments to SignatureHelp types (@michaelpj)
- Add support for InsertReplaceEdit (@michaelpj)
- Add support for InsertTextMode (@michaelpj)
- Add resolveSupport (@michaelpj)
- Fix applying a TextEdit past the end of the document (#271) (@michaelpj)
- Use Empty instead of () as progress create response (#295) (@wz1000)
- Add tag support for DocumentSymbol, SymbolInformation, and document symbol provider label (#301) (@michaelpj)
- Support change annotations (#302) (@michaelpj)
- Add some more missing lenses (#307) (@michaelpj)
1.1.0.0 – 2021-02-14
- Fix prepareRename reponse and prepareProvider (@kirelagin)
- Fix deriving instance of MonadUnliftIO (@banacorn)
- Add support for file and folder operations in WorkspaceEdit (@banacorn) Instead of having TextDocumentEdit in WorkspaceEdit
data WorkspaceEdit =
WorkspaceEdit
{ _changes :: Maybe WorkspaceEditMap
, _documentChanges :: Maybe (List TextDocumentEdit)
} deriving (Show, Read, Eq)
It is now replaced by a new type called DocumentChange
data WorkspaceEdit =
WorkspaceEdit
{ _changes :: Maybe WorkspaceEditMap
, _documentChanges :: Maybe (List DocumentChange)
} deriving (Show, Read, Eq)
Which is just a synonym of union of WorkspaceEdit and other operations
type DocumentChange = TextDocumentEdit |? CreateFile |? RenameFile |? DeleteFile
- Add new CodeAction features (isPreferred, disabled) (@pepeiborra)
- Respond to requests with missing handlers (@wz1000)
- Use Text over String in more places (@wz1000)
- Add missing lenses (@wz1000, @bubba)
1.0.0.0 – 2020-10-15
1.0.0.0 is a major rework with both internal and external facing changes, and will require manual migration.
- The package has been renamed from
haskell-lsp
tolsp
, and similarly forhaskell-lsp-types
tolsp-types
- Because of this, all modules are now exported from
Language.LSP.X
rather thanLanguage.Haskell.X
.
- Because of this, all modules are now exported from
- Both
lsp
andlsp-types
have been reworked to be much more type safe - The 3.15 specification should be fully supported now. If you find anything in the specification that isn’t in lsp-types, please let us know
- The Capture module has been removed as it will be reworked later on and moved to lsp-test
lsp
can now handle dynamic registration through theregisterCapability
andunregisterCapability
functions
### Type safety
There are three types of concrete messages, NotificationMessage
,
RequestMessage
and ResponseMessage
. They are parameterised by their
Method
, which determines what type their parameters or response result must be.
data RequestMessage (m :: Method f Request) = RequestMessage
{ _jsonrpc :: Text
, _id :: LspId m
, _method :: SMethod m
, _params :: MessageParams m
}
A Method
in turn is parameterised by whether it originates from the client or
the server, and whether it is used for notifications or requests:
TextDocumentFoldingRange :: Method FromClient Request
TextDocumentSelectionRange :: Method FromClient Request
WindowShowMessage :: Method FromServer Notification
WindowShowMessageRequest :: Method FromServer Request
Each Method
also has a singleton counterpart which allows it to be used at the
term level, for example in RequestMessage._method
:
STextDocumentFoldingRange :: SMethod TextDocumentFoldingRange
STextDocumentSelectionRange :: SMethod TextDocumentSelectionRange
SWindowShowMessage :: SMethod WindowShowMessage
SWindowShowMessageRequest :: SMethod WindowShowMessageRequest
The type families MessageParams
and ResponseResult
map each Method
to the
appropriate type to be used in a response:
ResponseResult TextDocumentRename = WorkspaceEdit
ResponseResult TextDocumentPrepareRename = Range |? RangeWithPlaceholder
Also new is the |?
type which represents union types in
TypeScript,
and is used throughout the specification where a field can accept several
different types.
As an example of this in action, the types of your handlers will now depend on whether or not they are a request or a notification. They will pass along the precise type for the parameters the method you are handling, and in the case of a request handler, will expect that the response you give back is of the correct type as well.
type family Handler (f :: Type -> Type) (m :: Method from t) = (result :: Type) | result -> f t m where
Handler f (m :: Method _from Request) = RequestMessage m -> (Either ResponseError (ResponseResult m) -> f ()) -> f ()
Handler f (m :: Method _from Notification) = NotificationMessage m -> f ()
LspT
LspFuncs
has been removed and instead functionality is exposed through
functions in the MonadLsp
class.
getVirtualFile :: MonadLsp config m => NormalizedUri -> m (Maybe VirtualFile)
sendRequest :: forall (m :: Method FromServer Request) f config. MonadLsp config f
=> SServerMethod m
-> MessageParams m
-> (Either ResponseError (ResponseResult m) -> f ())
-> f (LspId m)
It is parameterised over the server’s LSP configuration type and the underlying
monad.
We recommend that you build your own monad for your server on top of the LspT
transformer, so it will automatically become an instance of MonadLsp
.
Inside the new ServerDefinition
data type which gets passed to runServer
,
you need to specify how to convert from IO to your monad and back in
interpretHandler
so that lsp
can execute your monad inside the handlers. You
can use the result returned from doInitialize
to pass along the
LanguageContextEnv
needed to run an LspT
, as well as anything else your
monad needs.
type
ServerDefinition { ...
, doInitialize = \env _req -> pure $ Right env
, interpretHandler = \env -> Iso
(runLspT env) -- how to convert from IO ~> m
liftIO -- how to convert from m ~> IO
}
Steps to migrate
- In your
.cabal
file change anyhaskell-lsp
dependencies tolsp
- Replace your existing imports with
Haskell.LSP.Server
- If necessary define your own monad and fill in
interpretHandler
- Migrate your handlers to use
notificationHandler
andrequestHandler
, passing along the correspondingSMethod
(Seeexample/Simple.hs
) - Remove any storage/use of
LspFuncs
and instead call the corresponding functions directly from your monad instead ofIO
0.23.0.0 – 2020-10-05
- Add runWith for transporots other than stdio (@paulyoung)
- Fix race condition in event captures (@bgamari)
- Tweak the sectionSeparator (@alanz)
- Add hashWithSaltInstances (@ndmitchell)
- Fix CompletionItem.tags not being optional (@bubba)
- Avoid unnecessary normalisation in Binary instance for NormalizedFilePath (@cocreature)
- Fix ordering of TH splices (@fendor)
0.22.0.0 – 2020-05-04
- ResponseMessage results are now an Either type (@greenhat)
- Support for GHC 8.10.1
0.21.0.0 – 2020-03-21
- Stop getCompletionPrefix from crashing if beforePos is empty
- Add DidChangeWatchedFilesRegistrationOptions
- Add NormalizedFilePath from ghcide
- Add diagnostic and completion tags
- Fix language server example
- Correctly fix the problem with ‘$/’ notifications
- Add azure ci
0.20.0.0 – 2020-02-04T
- Force utf8 encoding when writing vfs temp files
- Don’t log errors for ‘$/’ notifications (@jinwoo)
- Force utf8 encoding when writing vfs temp files (@jneira)
- Store a hash in a NormalizedUri (@mpickering)
- Move “Semigroup WorkspaceEdit” instance (@sheaf)
- Fix vfs line endings (@jneira)
0.19.0.0 – 2019-12-14
- Fix vfs line endings (@jneira)
- Fix typo in .cabal (@turion)
- Normalize file paths before converting to Uri’s (@jneira)
- Fixes to persistVirtualFile (@mpickering)
0.18.0.0 – 2019-11-17
- Fix response type for CodeLensResolve, add the ContentModified error code (@SquidDev)
- Add missing fmClientPrepareRenameRequest to MessageFuncs export (@alanz)
- Rework Core.Options and infer all server capabilities from handlers (@bubba)
- Generate lenses for WorkDoneProgress data types (@alanz)
0.17.0.0 – 2019-10-18
- Update progress reporting to match the LSP 3.15 specification (@cocreature)
- Ensure ResponseMessage has either a result or an error (@cocreature)
0.16.0.0 – 2019-09-07
- Add support for CodeActionOptions (@thomasjm)
- Add support for
textDocument/prepareRename
request (@thomasjm) - Fix diagnostic code parsing (@thomasjm)
- Fix shutdown response type (@bubba)
- Relax base constraints for GHC 8.8 (@bubba)
0.15.0.0 – 2019-07-01
- Normalize URIs to avoid issues with percent encoding (@cocreature)
0.14.0.1 – 2019-06-13
- Fix Haddock error
0.14.0.0 – 2019-06-13
- Add support for custom request and notification methods (@cocreature)
0.11.0.0 – 2019-04-28
- Fix
window/progress/cancel
notification being a from server notification when it should be a from client notification - Fix typo in FoldingRange request name
0.10.0.0 – 2019-04-22
- Add types for
window/progress
notifications.
0.8.3.0 – unpublished
- Add
MarkupContent
toHoverResponse
, and (some) json roundtrip tests.
0.8.2.0 – 2019-04-11
- Add
applyTextEdit
andeditTextEdit
helpers
0.8.0.1 – 2018-10-27
- Support GHC 8.6.1 by loosening constraints. Via @domenkozar
0.8.0.0 – 2018-09-08
- Update Hover to be a nullable according to spec
- Move Lenses into a separate module,
Language.Haskell.LSP.Types.Lens
0.7.0.0 – 2018-08-14
- Update CompletionItem
- Add
commitCharacters
field - Add
MarkupContent
option fordocumentation
- Add
preselect
field - Add CompletionContext
- Add new server capabilities
- Add workspace folder support
- Add document color and color presentation
- Add folding range support
- Add goto type support
- s/TH/Types/g
- Move all types into haskell-lsp-types
- Hide Language.Haskell.LSP.TH.DataTypesJSON - Use Language.Haskell.LSP.Types instead
- Add lenses for Language.Haskell.LSP.Types.Capabilities
0.6.0.0 – 2018-08-06
- Add new DocumentSymbol type and hierarchal support
- Rename CommandOrCodeAction to CAResult
0.5.0.0 – 2018-08-03
- Update Command.arguments to match specification
- Update ClientCapabilities to v3.10
- Add MarkupContent
- Add new CompletionKinds
- Add new SymbolKinds
- Add preset version capabilities
0.4.0.0 – 2018-07-10
- CodeAction support as per v3.8 of the specification, by @Bubba
- Update VersionedTextDocumentIdentifier to match specification, by @Bubba.
0.3.0.0 – unpublished
- Handle TextDocumentSync fallbacks with new TDS type.
0.2.3.0 – unpublished
- GHC 8.4.3 support
- Introduce additional error codes as per the LSP spec. By @Bubba
0.2.2.0 – 2018-05-04
- Make Diagnostic relatedInformation optional, as per the LSP Spec. By @Bubba.
0.2.1.0 – 2018-05-02
- Broken out from the haskell-lsp package, to simplify development by not having to run massive TH processes when working on the framework.