Safe Haskell	Safe-Inferred
Language	GHC2021

Ide.Plugin.Error

Contents

Plugin Error Handling API

Synopsis

data PluginError
toErrorCode :: PluginError -> LSPErrorCodes |? ErrorCodes
toPriority :: PluginError -> Priority
handleMaybe :: Monad m => e -> Maybe b -> ExceptT e m b
handleMaybeM :: Monad m => e -> m (Maybe b) -> ExceptT e m b
getNormalizedFilePathE :: Monad m => Uri -> ExceptT PluginError m NormalizedFilePath

Plugin Error Handling API

data PluginError Source #

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 Source #
Instance details Defined in Ide.Plugin.Error Methods pretty :: PluginError -> Doc ann # prettyList :: [PluginError] -> Doc ann #

toErrorCode :: PluginError -> LSPErrorCodes |? ErrorCodes Source #

Converts to ErrorCode used in LSP ResponseErrors

toPriority :: PluginError -> Priority Source #

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 :: Monad m => e -> Maybe b -> ExceptT e m b Source #

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

getNormalizedFilePathE :: Monad m => Uri -> ExceptT PluginError m NormalizedFilePath Source #