🦀 Qlue-ls 🦀

⚡Qlue-ls (pronounced "clueless") is a blazingly fast language server for SPARQL, written in Rust 🦀.

To learn more about the origin story of this project, read the blog post.

🚀 Getting Started

📦 Installation

Qlue-ls is available on crate.io:

cargo install qlue-ls

And on PyPI:

pipx install qlue-ls

You can also build it from source:

git clone https://github.com/IoannisNezis/Qlue-ls.git
cd Qlue-ls
cargo build --release --bin qlue-ls

CLI Usage

To run Qlue-ls as formatter run:

qlue-ls format <PATH>

To run Qlue-ls as language server run:

qlue-ls server

This will create a language server listening on stdio.

with Neovim

After you installed the language server, add this to your init.lua:

vim.api.nvim_create_autocmd({ 'FileType' }, {
  desc = 'Connect to Qlue-ls',
  pattern = { 'sparql' },
  callback = function()
    vim.lsp.start {
      name = 'qlue-ls',
      cmd = { 'qlue-ls', 'server' },
      root_dir = vim.fn.getcwd(),
      on_attach = function(client, bufnr)
        vim.keymap.set('n', '<leader>f', vim.lsp.buf.format, { buffer = bufnr, desc = 'LSP: ' .. '[F]ormat' })
      end,
    }
  end,
})

Open a .rq file and check that the buffer is attached to th server:

:checkhealth lsp

Configure keymaps in on_attach function.

🚀 Capabilities

📐 Formatting

Status: Full support

Formats SPARQL queries to ensure consistent and readable syntax. Customizable options to align with preferred query styles are also implemented.

🩺 Diagnostics

Status: Partial support

Diagnostics provide feadback on the query.
Diagnostics come in severity: error, warning and info

** provided diagnostics**:

Type	Name	Description
❌ error	undefined prefix	a used prefix is not declared
❌ error	ungrouped select variable	selected variable is not grouped
❌ error	invalid projection variable	projection variable is taken
⚠️ warning	unused prefix	a declared prefix is not used
ℹ️ info	uncompacted uri	a raw uncompacted uri is used

✨ Completion

Status: Full support

Completion provides suggestions how the query could continue.

For completion of subjects, predicates or objects the language server sends completion-queries to the backend and gets the completions from the knowledge-graph.

These completion queries have to be configured for each knowledge-graph.

🛠️ Code Actions

Status: Partial support

name	description	diagnostic
shorten uri	shorten uri into compacted form	uncompacted uri
declare prefix	declares undeclared prefix (if known)	undeclared prefix
shorten all uri's	shorten all uri's into compacted form
add to result	add variable to selected result
filter variable	add filter for this variable

⚙️ Configuration

Qlue-ls can be configured through a qlue-ls.toml or qlue-ls.yml file.

Here is the full default configuration

[format]
align_predicates = true
align_prefixes = true
separate_prolouge = false
capitalize_keywords = true
insert_spaces = true
tab_size = 10
where_new_line = true
filter_same_line = true

[completion]
timeout_ms = 5000
result_size_limit = 42

🌐 use in web

If you want to connect from a web-based-editor, you can use this package as well.
For this purpose this can be compiled to wasm and is available on npm:

npm i qlue-ls

You will have to wrap this in a Web Worker and provide a language server client. There will be more documentation on this in the future...

Until then you can check out the demo in ./editor/

🏗 Development Setup

Here is a quick guide to set this project up for development.

Requirements

• rust >= 1.83.0
• wasm-pack >= 0.13.1
• node & npm >= 22.14.0 & >= 11.3.0
• [Optional] just
• [Optional] watchexec

Initial Setup

You will only have to do this once.

In the justfile and Makefile you will find the target init_dev, run it:

just init_dev

or

make init_dev

It will:

• install node dependencies
• build wasm binaries
• link against local packages
• run the vite dev server

If you don't have just or make installed:

Install just

Automatically rebuild on change

When developping the cycle is:

• Change the code
• Compile to wasm (or run tests)
• Evaluate

To avoid having to run a command each time to Compile I strongly recommend setting up a auto runner like watchexec.

watchexec --restart --exts rs --exts toml just build-wasm

or just:

just watch-and-run build-wasm

have fun!

🙏 Special Thanks

• TJ DeVries for the inspiration and great tutorials
• Chris Biscardi for teaching me Rust