Metadata-Version: 2.4
Name: q-lang-server
Version: 1.0.3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Rust
License-File: crates/q-lang-server/LICENSE.txt
Summary: q language server, written in Rust.
Keywords: kdb,q,language-server,lsp
Author-email: Jo Shinonome <jo.shinonome@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.7
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/jshinonome/vscode-q/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/jshinonome/vscode-q

# q-lang-server

Offline [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) implementation for **q** and **k**, written in Rust and powered by [tree-sitter](https://tree-sitter.github.io/tree-sitter/).

The server binary is named `qls`.

## Install

```bash
pip install q-lang-server
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install q-lang-server
```

This installs the `qls` executable on your `PATH`.

## Features

- **Diagnostics** (linter)
- **Document formatting**
- Go to definition
- Find references
- Rename symbol (with prepare rename)
- Hover
- Document symbols and workspace symbols
- Document highlight
- Completion (with resolve)
- Signature help
- Semantic tokens

Source files are analyzed offline from the workspace. By default the server looks under `**/src/**/*.q` and `**/src/**/*.k`. Add `;` to mark statement ends when needed for more accurate parsing.

### Formatter

The formatter keeps lines within 100 characters and produces stable output — formatting an already formatted file changes nothing.

Long symbol lists are wrapped with a trailing `,` so each continuation line still joins into the same list:

```q
longSyms: `symbol000`symbol001`symbol002`symbol003`symbol004`symbol005`symbol006`symbol007,
  `symbol008`symbol009`symbol010`symbol011`symbol012`symbol013`symbol014`symbol015`symbol016;
```

Symbol lists inside q-sql phases are left as-is, since a `,` there separates columns or conditions.

### Ignore directives

Place either comment above a block to skip analysis for that block:

```q
// q-lang-server-ignore-linter
// q-lang-server-ignore-formatter
```

## Editor setup

### Neovim

Use [chili-neovim](https://github.com/jshinonome/chili-neovim) for q/k syntax, process management, and LSP. It starts `qls` for `.q` / `.k` buffers by default.

1. Install `qls` (see above) and ensure it is on your `$PATH`.
2. Install chili-neovim with [lazy.nvim](https://github.com/folke/lazy.nvim):

Minimal:

```lua
{ "jshinonome/chili-neovim" }
```

With options and completion:

```lua
{
  "jshinonome/chili-neovim",
  main = "chili",
  dependencies = {
    "hrsh7th/nvim-cmp",
    "hrsh7th/cmp-nvim-lsp",
    "hrsh7th/cmp-buffer",
    "hrsh7th/cmp-vsnip",
    "hrsh7th/vim-vsnip",
  },
  opts = {
    qls = {
      cmd = { "qls" },
      filetypes = { "q" }, -- .q and .k
      document_highlight = true,
      format_on_save = true,
    },
  },
}
```

See the [chili-neovim README](https://github.com/jshinonome/chili-neovim) for process config, commands, and keybindings.

### Other editors

Any LSP client that can launch `qls` over stdio can use this server. Point the client at the `qls` binary and associate it with `q` and `k` filetypes.

## Related

- [chili-neovim](https://github.com/jshinonome/chili-neovim) — Neovim plugin for kdb+/q
- [vscode-q](https://github.com/jshinonome/vscode-q) — VS Code / Cursor extension that embeds this language server
- [Changelog](https://github.com/jshinonome/vscode-q/blob/main/CHANGELOG.md)

## License

Licensed under the [Apache License, Version 2.0](https://github.com/jshinonome/vscode-q/blob/main/crates/q-lang-server/LICENSE.txt).

