hls-plugin-api-2.9.0.0: Haskell Language Server API for plugin communication

Safe Haskell | None
Language | GHC2021

Ide.Plugin.Error

Contents

- Plugin Error Handling API

Synopsis

- data PluginError
  - = PluginInternalError Text
  - | PluginInvalidParams Text
  - | PluginInvalidUserState Text
  - | PluginRequestRefused RejectionReason
  - | PluginRuleFailed Text
  - | PluginStaleResolve
- toErrorCode :: PluginError -> LSPErrorCodes |? ErrorCodes
- toPriority :: PluginError -> Priority
- handleMaybe :: forall (m :: Type -> Type) e b. Monad m => e -> Maybe b -> ExceptT e m b
- handleMaybeM :: Monad m => e -> m (Maybe b) -> ExceptT e m b
- getNormalizedFilePathE :: forall (m :: Type -> Type). Monad m => Uri -> ExceptT PluginError m NormalizedFilePath

# Plugin Error Handling API

data PluginError #

Each PluginError corresponds to either a specific ResponseError we want to return or a specific way we want to log the error. If the currently present ones are insufficient for the needs of your plugin, please feel free to add a new one.

Currently the PluginErrors we provide can be broken up into several groups. First is PluginInternalError, which is the most serious of the errors, and also the "default" error that is used for things such as uncaught exceptions. Then we have PluginInvalidParams, which along with PluginInternalError map to a corresponding ResponseError.

Next we have PluginRuleFailed and PluginInvalidUserState, with the only difference being PluginRuleFailed is specific to Shake rules and PluginInvalidUserState can be used for everything else. Both of these are "non-errors", and happen whenever the user's code is in a state where the plugin is unable to provide a answer to the users request. PluginStaleResolve is similar to the above two Error types, but is specific to resolve plugins, and is used only when the data provided by the resolve request is stale, preventing the proper resolution of it.

Finally we have the outlier, PluginRequestRefused, where we allow a handler to preform "pluginEnabled" checks inside the handler, and reject the request after viewing it. The behavior of only one handler passing `pluginEnabled` and then returning PluginRequestRefused should be the same as if no plugins passed the `pluginEnabled` stage.

Constructors

PluginInternalError Text

PluginInternalError should be used if an error has occurred. This should only rarely be returned. As it's logged with Error, it will be shown by the client to the user via `showWindow`. All uncaught exceptions will be caught and converted to this error.

This error will be be converted into an InternalError response code. It will be logged with Error and takes the highest precedence (1) in being returned as a response to the client.

PluginInvalidParams Text

PluginInvalidParams should be used if the parameters of the request are invalid. This error means that there is a bug in the client's code (otherwise they wouldn't be sending you requests with invalid parameters).

This error will be will be converted into a InvalidParams response code. It will be logged with Warning and takes medium precedence (2) in being returned as a response to the client.

PluginInvalidUserState Text

PluginInvalidUserState should be thrown when a function that your plugin depends on fails. This should only be used when the function fails because the user's code is in an invalid state.

This error takes the name of the function that failed. Prefer to catch this error as close to the source as possible.

This error will be logged with Debug, and will be converted into a RequestFailed response. It takes a low precedence (3) in being returned as a response to the client.

PluginRequestRefused RejectionReason

PluginRequestRefused allows your handler to inspect a request before rejecting it. In effect it allows your plugin to act make a secondary `handlesRequest` decision after receiving the request. This should only be used if the decision to accept the request can not be made in `handlesRequest`.

This error will be with Debug. If it's the only response to a request, HLS will respond as if no plugins passed the `handlesRequest` stage.

PluginRuleFailed Text | PluginRuleFailed should be thrown when a Rule your response depends on fails. This error takes the name of the Rule that failed. This error will be logged with Debug, and will be converted into a RequestFailed response code. It takes a low precedence (3) in being returned as a response to the client.
PluginStaleResolve | PluginStaleResolve should be thrown when your resolve request is provided with data it can no longer resolve. This error will be logged with Debug, and will be converted into a ContentModified response. It takes a low precedence (3) in being returned as a response to the client.

#### Instances

Instances details

Pretty PluginError # |
Instance details Defined in Ide.Plugin.Error Methods pretty :: PluginError -> Doc ann # prettyList :: [PluginError] -> Doc ann #

toErrorCode :: PluginError -> LSPErrorCodes |? ErrorCodes #

Converts to ErrorCode used in LSP ResponseErrors

toPriority :: PluginError -> Priority #

Converts to a logging priority. In addition to being used by the logger, `combineResponses` currently uses this to choose which response to return, so care should be taken in changing it.

handleMaybe :: forall (m :: Type -> Type) e b. Monad m => e -> Maybe b -> ExceptT e m b #

handleMaybeM :: Monad m => e -> m (Maybe b) -> ExceptT e m b #

getNormalizedFilePathE :: forall (m :: Type -> Type). Monad m => Uri -> ExceptT PluginError m NormalizedFilePath #