Documentation

The provenance of a report, for use in logs.

Render a ReportContext by interspersing it with dots, returning Nothing if it is empty.

Render a ReportContext by interspersing it with dots, followed by a colon, returning Nothing if it is empty.

Render a ReportContext by interspersing it with dots, using global if it is empty.

Render a ReportContext by interspersing it with dots, followed by a colon, using global if it is empty.

An report with different messages intended to be sent to Neovim and the log, respectively.

Used by request handlers and expected by the RPC dispatcher.

Also contains the Severity of the report, or minimum log level, which determines whether the report should be logged and echoed in Neovim, and what kind of highlighting should be used in Neovim (red for errors, orange for warnings, none for infomrational errors).

The log message may span multiple lines.

The type used by request handlers and expected by the RPC dispatcher.

Construct a LogReport error from a single Text.

Stop with a LogReport.

The class of types that are convertible to a Report.

This is used to create a uniform format for handlers, since control flow is passed on to the internal machinery when they return. If an error would be thrown that is not caught by the request dispatcher, the entire plugin would stop, so all Stop and Resumable effects need to be converted to Report before returning (see Errors).

The combinators associated with this class make this task a little less arduous:

data NumbersError = InvalidNumber

instance Reportable NumbersError where
  toReport InvalidNumber = Report "Invalid number!" ["The user entered an invalid number"] Warn

count :: Int -> Sem r Int
count i =
  resumeReport @Rpc $ mapReport @NumbersError do
    when (i == 0) (stop InvalidNumber)
    nvimGetVar ("number_" <> show i)

Here resumeReport converts a potential RpcError from nvimGetVar to Report (e.g. if the variable is not set), while mapReport uses the instance Reportable NumbersError to convert the call to stop.

Reinterpret Stop err to Stop Report if err is an instance of Reportable.

Map multiple errors to Report.

Convert the effect eff to Resumable err eff and Stop Report if err is an instance of Reportable.

Resume multiple effects as Reports.

Extract both user and log messages from an Report, for use in tests.

Extract the user message from an instance of Reportable.

Resume an effect with an error that's an instance of Reportable by passing its user message to a function.

Map an error that's an instance of Reportable by passing its user message to a function.

Convert an error that's an instance of Reportable to Fail, for use in tests.

Resume an effect with an error that's an instance of Reportable by reinterpreting to Fail, for use in tests.