lang

Documentation

Overview

Package lang provides editor intelligence for DTL — completions, diagnostics, hover and signature help.

Nothing here serves anything. Every entry point is a pure function: text and a cursor in, structured results out. Transport is the caller's business, so the same functions back an HTTP handler, a WebSocket session, an SSE stream or an LSP binary without knowing which is which.

What the host knows and the language does not — which functions are registered, which datasets exist, which ambient values are in scope — is passed per call in a Context rather than read from a global. One process can therefore serve several workspaces without them seeing each other's names.

Index

• func Signature(name string, ctx Context) (params int, ok bool)
• type Context
• type Dataset
• type Function
• type Global
• type HoverInfo
  • func Hover(source string, position int, ctx Context) *HoverInfo
• type Item
  • func Complete(source string, position int, ctx Context) []Item
• type Kind

Functions

func Signature

func Signature(name string, ctx Context) (params int, ok bool)

Signature reports the parameter count for a callable, so an editor can show signature help. ok is false when the name is not callable here.

Types

type Context

type Context struct {
	Functions []Function
	Datasets  []Dataset
	Globals   []Global
}

Context carries host knowledge into a completion or hover request. Every field is optional: an empty Context yields language-only results — keywords, types and whatever the caller passed — which is exactly what an editor with no server reachable should still get.

type Dataset

type Dataset struct {
	Name       string
	Detail     string
	InsertText string
}

Dataset is a named data source the host offers as a completion. Detail and InsertText are the host's, because how a dataset is referenced in source is the host's convention, not the language's — one platform writes query("name"), another writes a bare identifier.

type Function

type Function struct {
	Name string
	// Params is the parameter count, used to build the insert text.
	Params int
	// Builtin distinguishes language builtins from user-defined functions,
	// which rank differently and carry different detail text.
	Builtin bool
	Doc     string
}

Function is a callable the host has registered, builtin or user-defined.

type Global

type Global struct {
	Name string
	Doc  string
	Keys []string
}

Global is an ambient object available to every program, and optionally the keys it exposes — environment names, secret names.

type HoverInfo

type HoverInfo struct {
	Word string `json:"word"`
	Doc  string `json:"documentation"`
}

HoverInfo is documentation for one token.

func Hover

func Hover(source string, position int, ctx Context) *HoverInfo

Hover returns documentation for the token under the cursor, or nil when the cursor is not on something documented.

type Item

type Item struct {
	Label      string `json:"label"`
	Kind       Kind   `json:"kind"`
	Detail     string `json:"detail,omitempty"`
	InsertText string `json:"insertText,omitempty"`
	Doc        string `json:"documentation,omitempty"`
}

Item is one completion suggestion.

func Complete

func Complete(source string, position int, ctx Context) []Item

Complete returns the suggestions for a cursor position in source.

Ordering is deliberate and part of the contract: keywords first, then functions, then types, then everything else, alphabetically within each group. Editors that do their own sorting will override it; those that do not get a usable list.

type Kind

type Kind string

Kind classifies a completion item for an editor's icon and ranking.

const (
	KindKeyword  Kind = "keyword"
	KindType     Kind = "type"
	KindFunction Kind = "function"
	KindVariable Kind = "variable"
	KindProperty Kind = "property"
)