LuaLS / LuaLS/lua-language-server

Add `upvalue` semantic token modifier

Aperta
#3,456 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Lingua principale
Lua
Stelle
4.4k
Fork
442
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

LuaLS should expose whether a `variable` reference is an upvalue through a new `upvalue` semantic token modifier.

Currently, local variables and upvalues are both reported as:

```text
semantic token type: variable
modifiers: -
```

while globals are already distinguished using:

```text
semantic token type: variable
modifiers: global
```

This makes it impossible for editors such as VS Code to visually distinguish local variables from upvalues.

## Example

```lua
local function outer()
local value = 123

return function()
print(value) -- upvalue
end
end
```

Currently the `value` reference inside the inner function is:

```text
variable
```

It would be useful for LuaLS to report it as:

```text
variable + upvalue
```

while the declaration remains:

```text
variable
```

## Proposed semantic token model

```text
variable -> local variable
variable + upvalue -> upvalue
variable + global -> global variable
parameter -> function parameter
```

For example:

```lua
local foo = 1

local function outer(bar)
local baz = 2

return function(qux)
print(foo) -- upvalue
print(bar) -- upvalue
print(baz) -- upvalue
print(qux) -- parameter
print(print) -- global
end
end
```

would produce approximately:

```text
foo -> variable + upvalue
bar -> variable + upvalue
baz -> variable + upvalue
qux -> parameter
print -> variable + global
```

Ordinary locals would remain simply:

```text
variable
```

## Why a modifier?

A modifier seems preferable to introducing a new semantic token type because `upvalue` describes a property of a variable reference rather than a fundamentally different kind of symbol.

It also fits the existing LuaLS representation of globals:

```text
variable + global
```

This gives editor themes a simple way to distinguish all four cases:

```text
variable
variable + upvalue
variable + global
parameter
```

## Scope

The `upvalue` modifier should be applied to references resolved to a variable declared in an enclosing lexical scope.

For example:

```lua
local x = 1

local function f()
print(x)
end
```

would be:

```text
x declaration -> variable
x reference -> variable + upvalue
```

Nested closures should work recursively.

## Motivation

This would allow VS Code themes to use different colors for locals, parameters, upvalues, and globals, making lexical scope much easier to understand in closure-heavy Lua/LuaJIT code.

LuaLS already performs the necessary lexical-scope resolution; this proposal would expose that information through semantic tokens.

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

La issue non indica file né test. Inizia individuando la generazione dei token semantici di LuaLS e la risoluzione dell’ambito lessicale usata per i riferimenti alle variabili; segui come viene assegnato il modificatore globale esistente. Il lavoro è completato quando ai riferimenti risolti a variabili di ambiti esterni viene assegnato un modificatore upvalue, le dichiarazioni e le variabili locali ordinarie rimangono invariate e le closure annidate sono coperte dai test.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
lua
Ambito
devtools
Tipo di issue
Funzionalità
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
52/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.