# Editors

One toolchain serves every editor. `giz lsp` is the language server, and `giz debug --dap` is the debug adapter
([Debugging](debugging.md) is how to debug).
They give the same answers as `giz check` and `giz build`, so an editor shows what the compiler says.

- [Set up an editor](#set-up-an-editor): VS Code, Neovim or any editor that speaks LSP.
- [What the editor shows](#what-the-editor-shows): the features of the language server.

## Set up an editor

### VS Code

:::status{of="lsp"}
:::

The toolchain release carries the Gizlang extension. Install it, and again after each upgrade:

```sh
giz vscode
```

This runs `code --install-extension` on the release's `share/gizlang/vscode/gizlang.vsix`. It finds VS Code on `PATH`
(`code`, `code-insiders`, `codium`) or in its standard install folder (`/Applications` on macOS, where a first install
leaves `code` off `PATH`; `%LOCALAPPDATA%\Programs` on Windows). Without VS Code it says how to install it on your system.
With only `@gizai/cli` installed, `giz vscode` first installs the toolchain.

The extension starts `gizlang lsp` and `gizlang debug --dap`. It adds the Test Explorer, the `giz` task type with a problem
matcher, and the Run, Debug, Check and Test File commands. When `gizlang` is not on `PATH` or in `~/.giz/bin`, set `gizlang.path` to it; the
extension says so when the server does not start.

| Setting | Default | Meaning |
| --- | --- | --- |
| `gizlang.path` | `gizlang` | The Gizlang toolchain. Left as `gizlang`, the installed `~/.giz/bin/gizlang` runs when it is there. |
| `gizlang.server.args` | `["lsp"]` | The arguments that start the language server |
| `gizlang.trace.server` | `off` | Trace the messages between VS Code and the server |

### Neovim

For Neovim 0.11 and later, put this in `init.lua`. The lspconfig plugin is not necessary.

```lua
vim.filetype.add({ extension = { giz = 'gizlang', ghtml = 'ghtml' } })
vim.lsp.config('gizlang', {
  cmd = { 'giz', 'lsp' },
  filetypes = { 'gizlang', 'ghtml' },
  root_markers = { 'package.json', '.git' },
})
vim.lsp.enable('gizlang')
```

To debug with [nvim-dap](https://github.com/mfussenegger/nvim-dap), add `giz debug --dap` as an executable adapter:

```lua
local dap = require('dap')
dap.adapters.gizlang = { type = 'executable', command = 'giz', args = { 'debug', '--dap' } }
dap.configurations.gizlang = {
  { type = 'gizlang', request = 'launch', name = 'Debug file', program = '${file}', cwd = '${workspaceFolder}' },
}
```

### Other editors

An editor that speaks the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) starts
`giz lsp` on standard input and output for `.giz` and `.ghtml` files. An editor that speaks the
[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) starts `giz debug --dap` as its debug
adapter and launches a `.giz` file as its `program`.

In a Gizlang checkout, start `/absolute/path/to/gizlang/bin/gizlang` instead of `giz`, with `GIZLANG_BUILD` set to the
checkout's build folder in the editor's environment.

## What the editor shows

The server answers from the compiler, for `.giz` files and for the script and `{}` holes of `.ghtml` files:

- Diagnostics as you type, with the rule and its fix as a quick fix.
- Hover: a declaration's signature, doc and inferred effects; a local's inferred type.
- Go to definition, find references, and highlights of a name's uses in the file.
- Completion: the members of a value after `.`, the declarations in scope and the keywords; in a `.ghtml` file, the
  components a page may use and the directives of a tag. Signature help in calls.
- Rename of a declaration and its uses, checked by the compiler; formatting as `giz fmt`.
- Semantic highlighting, folding, inlay hints of the types of locals, and document and workspace symbols.
- Run and Debug code lenses above `main`, Run all tests above a test file's first test, and linked editing of a tag's name and its end tag.

In VS Code, the HTML and CSS of a `.ghtml` file also get the editor's own HTML and CSS features, and Emmet.

The [tools internals](../internals/tools.md#language-server) list the protocol requests and the limits of the server.
