Initial commit
[haskell-blog.git] / drafts / plugin.md
1 ---
2 title: 🔌 Making a HIE plugin
3 date: 2018-09-24
4 ---
5
6 haskell-ide-engine provides a lot of different language features, from giving diagnostics, to refactoring names and suggesting imports.
7 How does one server manage to do so much? Well the truth is that haskell-ide-engine is actually several plugins stacked on top of each other in a trenchcoat.
8 Most of the functionality comes from existing tools already in the ecosystem:
9
10 - ghc-mod provides the diagnostics
11 - HaRe provides refactoring
12 - hlint provides quick fixes
13 - hsimport provides import suggestions
14 - hoogle provides documentation 
15
16 HIE provides endpoints for these plugins to tap into various LSP features:
17
18 ```haskell
19 data PluginDescriptor =
20   PluginDescriptor { ...
21                    , pluginCodeActionProvider :: Maybe CodeActionProvider
22                    , pluginDiagnosticProvider :: Maybe DiagnosticProvider
23                    , pluginHoverProvider      :: Maybe HoverProvider
24                    , pluginSymbolProvider     :: Maybe SymbolProvider
25                    }
26 ```
27
28 # Code actions
29
30 ```haskell
31 type CodeActionProvider =  PluginId
32                         -> VersionedTextDocumentIdentifier
33                         -> Maybe FilePath -- ^ Project root directory
34                         -> Range
35                         -> CodeActionContext
36                         -> IdeM (IdeResult [CodeAction])
37 ```
38
39 ![Refactoring options](/images/refactor.png)
40
41 Code actions are the main method of exposing functionality to the client within LSP.
42 Whenever the client requests the code actions for the document, HIE will query your plugin with information about the current document and position, and you can return back any relevant code actions.
43 Where your code actions will appear (e.g. in the refactor menu or as quick-fix) is determined by the `CodeActionKind` of the `CodeAction`, so make sure to choose a type that is suitable for the type of action that you are providing:
44
45 ```haskell
46 data CodeActionKind = CodeActionQuickFix
47                     | CodeActionRefactor
48                     | CodeActionRefactorExtract
49                     | CodeActionRefactorInline
50                     | CodeActionRefactorRewrite
51                     | CodeActionSource
52                     | CodeActionSourceOrganizeImports
53 ```
54