LuaLS / LuaLS/lua-language-server
Add `upvalue` semantic token modifier
還沒有人認領這個 Issue。
- 主要語言
- Lua
- 星號
- 4.4k
- 分支
- 442
- PR 合併指標
- 30 天內沒有已合併 PR
描述
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.
貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
研究方向
Issue 沒有指出任何檔案或測試。首先定位 LuaLS 的語意 token 產生,以及用於變數參照的詞法作用域解析;追蹤現有 global modifier 的指派方式。完成的標準是:解析到外層作用域變數的參照會取得 upvalue modifier,宣告和一般區域變數維持不變,並且巢狀 closure 有測試涵蓋。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- lua
- 領域
- devtools
- Issue 類型
- 功能
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 活躍度
- 活躍
- 描述清晰度
- 基本清楚
- 新手友好度
- 52/100