LuaLS / LuaLS/lua-language-server
Add `upvalue` semantic token modifier
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Lua
- Estrellas
- 4.4k
- Forks
- 442
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Descripción
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.
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
El issue no menciona archivos ni tests. Empieza localizando la generación de tokens semánticos de LuaLS y la resolución del ámbito léxico utilizada para las referencias a variables; sigue cómo se asigna el modificador global existente. El trabajo estará terminado cuando las referencias resueltas a variables de ámbitos envolventes reciban un modificador upvalue, las declaraciones y las variables locales ordinarias permanezcan sin cambios, y las closures anidadas estén cubiertas por tests.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- lua
- Área
- devtools
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 52/100