Developer Tools

vlsp

A small language server, started with venutian lsp, for editor diagnostics.

Released v1.0.0 · 2026-09-28

Import

use "stdlib/lsp.ven"

A minimal Language Server Protocol server, written in pure Venutian and started with venutian lsp, giving an editor live diagnostics and lookups.

vlsp.ven

print crlf()

Reference (26 functions)

Wire framing
URI and filesystem path
Diagnostics
JSON-RPC responses
Hover / completion: real AST-sourced symbol info
Message dispatch
Functions

API reference

Wire framing

`crlf()`

Gives back the carriage-return character used by LSP wire framing.

crlf()

`send_message(obj)`

Writes one JSON-RPC message to standard output, real LSP framing included.

notification = new_map()
map_set(notification, "jsonrpc", "2.0")
map_set(notification, "method", "textDocument/publishDiagnostics")
send_message(notification)

`read_message()`

Reads one framed JSON-RPC message body off standard input.

body = read_message()

URI and filesystem path

`uri_to_path(uri)`

Converts an LSP document URI into a plain filesystem path.

uri_to_path("file:///tmp/example.ven")

Diagnostics

`error_to_diagnostic(check_error)`

Converts one vtypecheck.ven check error into an LSP Diagnostic.

err = new_map()
map_set(err, "line", 3)
map_set(err, "message", "type mismatch")
error_to_diagnostic(err)

`diagnostics_for_file(path)`

Runs vtypecheck.ven's real checker on path and returns LSP diagnostics.

diagnostics_for_file("stdlib/lsp.ven")

`publish_diagnostics_for(uri)`

Checks the file at uri and sends its diagnostics to the client.

publish_diagnostics_for("file:///tmp/example.ven")

JSON-RPC responses

`send_result(id_value, result_value)`

Sends a successful JSON-RPC response for the request id_value.

send_result(1, nothing)

`send_method_not_found(id_value, method_name)`

Sends a JSON-RPC "method not found" error response.

send_method_not_found(2, "textDocument/definition")

`initialize_result()`

Builds the initialize response's honest, minimal capabilities.

initialize_result()

Hover / completion: real AST-sourced symbol info

`is_identifier_char(ch)`

Tests whether ch can appear inside an identifier.

is_identifier_char("_")

`word_at_position(source_text, zero_based_line, zero_based_character)`

Finds the identifier under or immediately before a cursor position.

word_at_position("make add(a, b)\n    give a + b", 0, 6)

`document_structure_for(path)`

Parses path and returns its real, unfiltered top-level structure.

document_structure_for("stdlib/lsp.ven")

`param_signature_text(param_info)`

Renders one parameter info Map as its declaration-style text.

p = new_map()
map_set(p, "name", "text")
map_set(p, "type", nothing)
map_set(p, "has_default", no)
param_signature_text(p)

`function_signature_text(fn_info)`

Renders one function info Map as its full declaration line.

structure = document_structure_for("stdlib/lsp.ven")
fn = find_by_name(map_get(structure, "functions"), "crlf")
function_signature_text(fn)

`shape_field_text(field_info)`

Renders one shape field info Map as "name: Type".

f = new_map()
map_set(f, "name", "kind")
map_set(f, "type", "Text")
shape_field_text(f)

`shape_signature_text(shape_info_map)`

Renders one shape info Map as its full declaration line.

structure = document_structure_for("stdlib/doc.ven")
shape_decl = find_by_name(map_get(structure, "shapes"), "DocEntry")
shape_signature_text(shape_decl)

`find_by_name(items, name)`

Finds the first Map in items whose "name" field equals name.

items = [new_map()]
map_set(items[0], "name", "add")
find_by_name(items, "add")

`hover_contents_for(word, structure)`

Builds the hover text for word, looked up against structure.

hover_contents_for("run_server", document_structure_for("stdlib/lsp.ven"))

`handle_hover(id_value, params)`

Handles a "textDocument/hover" request.

params = new_map()
doc = new_map()
map_set(doc, "uri", "file:///tmp/example.ven")
map_set(params, "textDocument", doc)
position = new_map()
map_set(position, "line", 0)
map_set(position, "character", 5)
map_set(params, "position", position)
handle_hover(1, params)

`completion_item_for_function(fn_info)`

Builds one LSP CompletionItem for a real function declaration.

structure = document_structure_for("stdlib/lsp.ven")
fn = find_by_name(map_get(structure, "functions"), "crlf")
completion_item_for_function(fn)

`completion_item_for_shape(shape_info_map)`

Builds one LSP CompletionItem for a real shape declaration.

structure = document_structure_for("stdlib/doc.ven")
shape_decl = find_by_name(map_get(structure, "shapes"), "DocEntry")
completion_item_for_shape(shape_decl)

`handle_completion(id_value, params)`

Handles a "textDocument/completion" request.

params = new_map()
doc = new_map()
map_set(doc, "uri", "file:///tmp/example.ven")
map_set(params, "textDocument", doc)
handle_completion(1, params)

Message dispatch

`handle_open_or_change(params)`

Handles both "textDocument/didOpen" and "textDocument/didChange".

params = new_map()
doc = new_map()
map_set(doc, "uri", "file:///tmp/example.ven")
map_set(params, "textDocument", doc)
handle_open_or_change(params)

`handle_message(msg)`

Dispatches one decoded JSON-RPC message to its handler.

msg = new_map()
map_set(msg, "method", "initialize")
map_set(msg, "id", 1)
handle_message(msg)

`run_server()`

Runs the LSP server's read-decode-dispatch loop until it should stop.

run_server()