feat: add interactive attribute block toggle with keybindings and commands
Add ability to expand/collapse SCL variable attribute blocks like {EXTERNALACCESSIBLE := 'false'} to {...}
Features:
- Per-variable collapse rules via collapseVariableRules option
- Interactive toggle with <Leader>xa keybinding
- Commands: SCLToggleAttrBlock, SCLExpandAllAttrBlocks, SCLCollapseAllAttrBlocks
- Keybindings: <Leader>xa (toggle), <Leader>xae (expand all), <Leader>xac (collapse all)
- Supports both formatter-collapsed and manually collapsed blocks
Also update AGENTS.md with new documentation and troubleshooting guide
This commit is contained in:
@@ -1,59 +1,63 @@
|
||||
# AGENTS.md - SCL Language Server (Unified)
|
||||
# AGENTS.md - SCL Language Server
|
||||
|
||||
A unified Neovim/LazyVim plugin for Siemens SCL language support providing LSP, linting, formatting, syntax highlighting, and auto-completion.
|
||||
|
||||
## Reference Project for Testing
|
||||
|
||||
For manual testing and SCL/UDT/DB file examples, use:
|
||||
```
|
||||
~/dev/siemens/projects/scl_lang_support_lazyvim_ref_project
|
||||
```
|
||||
|
||||
## Build/Lint/Test Commands
|
||||
|
||||
### LSP Server
|
||||
```bash
|
||||
# LSP Server
|
||||
make start # Start LSP server
|
||||
make test # Run LSP in test mode
|
||||
lua src/main.lua --test # Direct test mode execution
|
||||
```
|
||||
lua src/main.lua --test # Direct test execution
|
||||
|
||||
### Tree-sitter Parser
|
||||
```bash
|
||||
# Tree-sitter Parser
|
||||
tree-sitter generate # Generate parser from grammar.js
|
||||
tree-sitter test # Run tree-sitter tests
|
||||
tree-sitter parse <file.scl> # Parse a single SCL file
|
||||
tree-sitter test # Run parser tests
|
||||
tree-sitter parse <file.scl> # Parse single SCL file
|
||||
|
||||
# Lua Linting
|
||||
luacheck src/ # Lint LSP server code
|
||||
luacheck lua/scl/ # Lint plugin modules
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
scl_lsp/
|
||||
├── src/ # Standalone LSP server (uses dofile)
|
||||
│ ├── main.lua # Entry point, JSON-RPC protocol
|
||||
│ ├── parser.lua # Regex-based SCL parser
|
||||
│ ├── diagnostics.lua # Linter diagnostics
|
||||
│ └── formatter.lua # Document formatter
|
||||
├── lua/scl/ # Neovim plugin modules (uses require)
|
||||
│ ├── blink_cmp_source.lua # blink.cmp completion source
|
||||
│ ├── udt_parser.lua # UDT (.udt) parser
|
||||
│ ├── db_parser.lua # Global DB (.db) parser
|
||||
│ ├── fb_parser.lua # Function Block parser
|
||||
│ ├── variables.lua # Local variable extraction
|
||||
│ ├── workspace_types.lua # Workspace scanning
|
||||
│ └── multiline_params.lua # FB parameter filling
|
||||
└── queries/ # Tree-sitter queries
|
||||
├── src/ # LSP server (uses dofile)
|
||||
│ ├── main.lua # Entry point, JSON-RPC protocol
|
||||
│ ├── parser.lua # SCL parser
|
||||
│ ├── diagnostics.lua # Linter
|
||||
│ ├── formatter.lua # Document formatter
|
||||
│ ├── treesitter.lua # Tree-sitter integration
|
||||
│ ├── plc_json.lua # External UDT loading
|
||||
│ └── json.lua # JSON encoder/decoder
|
||||
├── lua/scl/ # Neovim plugin (uses require)
|
||||
│ ├── init.lua # Main plugin setup
|
||||
│ ├── blink_cmp_source.lua
|
||||
│ ├── udt_parser.lua # UDT parser
|
||||
│ ├── db_parser.lua # Global DB parser
|
||||
│ ├── fb_parser.lua # Function Block parser
|
||||
│ ├── variables.lua # Variable extraction
|
||||
│ ├── workspace_types.lua # Workspace scanning
|
||||
│ ├── multiline_params.lua
|
||||
│ ├── auto_prefix.lua
|
||||
│ └── attr_toggle.lua # Interactive attribute block toggle
|
||||
├── queries/ # Tree-sitter queries
|
||||
│ ├── highlights.scm
|
||||
│ ├── indents.scm
|
||||
│ └── folds.scm
|
||||
└── grammar.js # Tree-sitter grammar
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Module Pattern
|
||||
All modules follow the standard Lua module pattern:
|
||||
```lua
|
||||
-- Module description comment at top
|
||||
-- File header comment
|
||||
local M = {}
|
||||
|
||||
-- Private module-level cache
|
||||
-- Private cache
|
||||
local cache = {}
|
||||
|
||||
function M.public_function()
|
||||
@@ -66,37 +70,37 @@ return M
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
- Functions/variables: `snake_case` (e.g., `get_udt_members`, `var_types`)
|
||||
- Functions/variables: `snake_case` (e.g., `get_udt_members`)
|
||||
- Constants: `UPPER_SNAKE_CASE` (e.g., `PROJECT_MARKERS`)
|
||||
- Private functions: declare as `local function` before public functions
|
||||
- Boolean variables: prefix with `is_`, `has_` (e.g., `is_udt`, `has_members`)
|
||||
- Booleans: prefix with `is_`, `has_` (e.g., `is_udt`, `has_members`)
|
||||
|
||||
### Imports
|
||||
- `lua/scl/` modules: use `require("scl.module_name")`
|
||||
- `src/` modules: use `dofile(script_path .. "/module.lua")`
|
||||
- External dependencies: wrap in `pcall()` for safety
|
||||
|
||||
### Comments
|
||||
- Every file must have a header comment explaining its purpose
|
||||
- All functions should have a brief comment describing what they do
|
||||
- Complex logic requires inline comments explaining the "why"
|
||||
- Non-obvious regex patterns must have explanatory comments
|
||||
### Code Formatting
|
||||
- `lua/scl/`: 2 spaces indentation
|
||||
- `src/`: tab-based indentation
|
||||
- Max line length: 120 characters
|
||||
- No trailing whitespace
|
||||
|
||||
### Parser Module API Convention
|
||||
All parser modules (udt_parser, db_parser, fb_parser) must implement:
|
||||
- `parse_*_file(filepath)` - Parse a file and cache result
|
||||
- `parse_*_content(content, filename)` - Parse string content
|
||||
- `get_*(name)` - Get single cached item by name
|
||||
- `get_all_*_names()` - Return list of all cached names
|
||||
- `get_*_members(name)` - Get members/fields for a type
|
||||
- `is_*_type(name)` - Check if name is a known type
|
||||
- `clear_cache()` - Clear all cached data
|
||||
- `get_cache_count()` - Return number of cached items
|
||||
### Parser Module API
|
||||
All parser modules must implement:
|
||||
- `parse_*_file(filepath)` - Parse and cache
|
||||
- `parse_*_content(content, filename)` - Parse string
|
||||
- `get_*(name)` - Get cached item
|
||||
- `get_all_*_names()` - List all cached names
|
||||
- `get_*_members(name)` - Get members/fields
|
||||
- `is_*_type(name)` - Check if known type
|
||||
- `clear_cache()` - Clear cached data
|
||||
- `get_cache_count()` - Return cache size
|
||||
|
||||
### Cache Management
|
||||
- Use module-level local tables for caching: `local cache = {}`
|
||||
- Clear caches by iterating and setting to nil, not by reassigning:
|
||||
```lua
|
||||
local cache = {}
|
||||
|
||||
function M.clear_cache()
|
||||
for k in pairs(cache) do
|
||||
cache[k] = nil
|
||||
@@ -106,21 +110,20 @@ end
|
||||
|
||||
## Lua Reserved Keywords
|
||||
|
||||
Lua reserved keywords (like `end`, `for`, `in`, etc.) cannot be used as table keys directly. Use bracket notation:
|
||||
Cannot use reserved keywords as table keys directly:
|
||||
```lua
|
||||
-- WRONG: causes syntax error
|
||||
-- WRONG: syntax error
|
||||
local range = { start = pos1, end = pos2 }
|
||||
|
||||
-- CORRECT: use bracket notation
|
||||
-- CORRECT: bracket notation
|
||||
local range = { start = pos1, ["end"] = pos2 }
|
||||
```
|
||||
|
||||
This is especially important for LSP range objects which require an `end` field per the LSP specification.
|
||||
Critical for LSP range objects with `end` field.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Return Pattern
|
||||
Functions that can fail return `nil, "error message"`:
|
||||
```lua
|
||||
function M.parse_file(filepath)
|
||||
local file = io.open(filepath, "r")
|
||||
@@ -133,7 +136,6 @@ end
|
||||
```
|
||||
|
||||
### External Dependencies
|
||||
Always wrap external requires in `pcall()`:
|
||||
```lua
|
||||
local ok, module = pcall(require, "some_module")
|
||||
if ok and module then
|
||||
@@ -141,72 +143,187 @@ if ok and module then
|
||||
end
|
||||
```
|
||||
|
||||
### Validation
|
||||
Check required parameters early and return sensible defaults:
|
||||
```lua
|
||||
function M.get_members(type_name)
|
||||
if not type_name then
|
||||
return {}
|
||||
end
|
||||
-- ... continue
|
||||
end
|
||||
```
|
||||
|
||||
## Completion System
|
||||
|
||||
### Trigger Characters
|
||||
## Completion Triggers
|
||||
- `#` - Local variables (after BEGIN)
|
||||
- `.` - Member access (UDT/DB members)
|
||||
- `.` - Member access (UDT/DB)
|
||||
- `"` - Global DB names
|
||||
- `(` - FB/Function parameters
|
||||
- ` ` (space) - General completion
|
||||
|
||||
### Active Portion Detection
|
||||
When matching patterns in completion, use the "active portion" of the line (after the last operator) to correctly handle expressions like:
|
||||
```scl
|
||||
"DB1".member := "DB2".member
|
||||
## Formatter Options
|
||||
|
||||
The formatter supports collapsing verbose attribute blocks:
|
||||
|
||||
```lua
|
||||
-- Before formatting:
|
||||
statCntrPartsIn{EXTERNALACCESSIBLE := 'false'; EXTERNALVISIBLE := 'false'} : Int;
|
||||
|
||||
-- After formatting:
|
||||
statCntrPartsIn{...} : Int;
|
||||
```
|
||||
Find the last `:=`, `=>`, `=`, `<>`, `>=`, `<=`, `>`, `<`, `AND`, `OR`, `NOT` and only match patterns after it.
|
||||
|
||||
### Formatter Configuration
|
||||
```lua
|
||||
local options = {
|
||||
insertSpaces = false,
|
||||
tabSize = 1,
|
||||
collapseAttributes = true, -- Enable attribute collapsing (default: true)
|
||||
collapsePatterns = { -- Override default patterns
|
||||
"^%s*{%s*EXTERNAL",
|
||||
"^%s*{ S7_",
|
||||
},
|
||||
extendCollapsePatterns = { -- Add custom patterns
|
||||
"^%s*{%s*CUSTOM",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Default Collapse Patterns
|
||||
- `^%s*{%s*EXTERNAL` - Variable attributes: `{EXTERNALACCESSIBLE := 'false'; ...}`
|
||||
- `^%s*{ S7_` - Block attributes: `{ S7_Optimized_Access := 'TRUE' }`
|
||||
- `^%s*{%s*%w+%s*:=` - Generic attributes with assignments
|
||||
|
||||
### Per-Variable Collapse Rules
|
||||
Control collapsing per variable using rules (evaluated before global patterns):
|
||||
|
||||
```lua
|
||||
local options = {
|
||||
collapseVariableRules = {
|
||||
-- Collapse attributes for variables starting with "stat"
|
||||
{
|
||||
variablePattern = "^stat",
|
||||
collapse = true,
|
||||
},
|
||||
-- Never collapse for "temp" prefix variables
|
||||
{
|
||||
variablePattern = "^temp",
|
||||
collapse = false,
|
||||
},
|
||||
-- Collapse only if both variable AND attribute match
|
||||
{
|
||||
variablePattern = "^config",
|
||||
attributePattern = "EXTERNAL",
|
||||
collapse = true,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Rule properties:**
|
||||
- `variablePattern` - Lua pattern to match variable name (optional)
|
||||
- `attributePattern` - Lua pattern to match attribute content (optional)
|
||||
- `collapse` - `true` to collapse to `{...}`, `false` to keep expanded
|
||||
|
||||
Rules are checked in order; first match wins.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `:SCLShowVariables` | Show local variables in current file |
|
||||
| `:SCLShowWorkspaceTypes` | Show workspace UDTs, FBs, and Global DBs count |
|
||||
| `:SCLRescanWorkspaceTypes` | Rescan workspace for types and DBs |
|
||||
| `:SCLPrefixWord` | Manually prefix current word with `#` |
|
||||
| `:SCLMultilineParams` | Fill multiline parameters for FB/Function call |
|
||||
| `:LspSCLFormat` | Format current SCL file |
|
||||
| `:SCLGeneratePlcJson` | Generate plc.data.json from data_types/ |
|
||||
| `:SCLShowVariables` | Show local variables |
|
||||
| `:SCLShowWorkspaceTypes` | Show workspace types count |
|
||||
| `:SCLRescanWorkspaceTypes` | Rescan workspace |
|
||||
| `:SCLPrefixWord` | Prefix word with `#` |
|
||||
| `:SCLMultilineParams` | Fill FB parameters |
|
||||
| `:LspSCLFormat` | Format SCL file |
|
||||
| `:SCLToggleAttrBlock` | Toggle attribute block under cursor |
|
||||
| `:SCLExpandAllAttrBlocks` | Expand all `{...}` blocks in buffer |
|
||||
| `:SCLCollapseAllAttrBlocks` | Collapse all matching attribute blocks |
|
||||
|
||||
## LSP Server Implementation Notes
|
||||
## Keybindings (SCL/UDT files)
|
||||
|
||||
### Attribute Block Toggle
|
||||
Interactive expand/collapse of individual `{...}` blocks (uses `<Leader>x` prefix):
|
||||
|
||||
| Key | Mode | Description |
|
||||
|-----|------|-------------|
|
||||
| `<Leader>xa` | Normal/Insert | Toggle block under cursor |
|
||||
| `<Leader>xae` | Normal | Expand all collapsed blocks |
|
||||
| `<Leader>xac` | Normal | Collapse all attribute blocks |
|
||||
|
||||
**How it works:**
|
||||
1. Place cursor inside any `{...}` block
|
||||
2. Press `<Leader>xa` to toggle between collapsed `{...}` and expanded content
|
||||
3. Original content is stored per-buffer and persists until buffer is closed
|
||||
4. Works on both formatter-collapsed blocks and manually collapsed ones
|
||||
|
||||
### Other Keybindings
|
||||
|
||||
| Key | Mode | Description |
|
||||
|-----|------|-------------|
|
||||
| `<Leader>xa` | Normal/Insert | Toggle attribute block under cursor |
|
||||
| `<Leader>xae` | Normal | Expand all attribute blocks |
|
||||
| `<Leader>xac` | Normal | Collapse all attribute blocks |
|
||||
| `<Space>mp` | Insert | Fill multiline FB parameters |
|
||||
| `<Tab>` | Insert | Jump to next parameter or regular Tab |
|
||||
|
||||
Note: `<Leader>` is typically `\` (backslash) or `<Space>` depending on your configuration.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**If commands or keybindings don't work:**
|
||||
|
||||
1. Check if setup() was called:
|
||||
```lua
|
||||
:lua print(vim.inspect(require("scl_lsp")))
|
||||
```
|
||||
|
||||
2. Verify commands exist:
|
||||
```vim
|
||||
:command SCLToggleAttrBlock
|
||||
```
|
||||
Should show the command definition.
|
||||
|
||||
3. Check for errors during setup:
|
||||
```lua
|
||||
:lua require("scl_lsp").setup({})
|
||||
```
|
||||
|
||||
4. Verify leader key:
|
||||
```vim
|
||||
:echo mapleader
|
||||
```
|
||||
If empty, your leader is `\` (backslash).
|
||||
|
||||
5. Manual test keybinding:
|
||||
```vim
|
||||
:nmap <Leader>xa
|
||||
```
|
||||
Should show the mapping.
|
||||
|
||||
## Testing
|
||||
|
||||
Manual testing using: `~/dev/siemens/projects/scl_lang_support_lazyvim_ref_project`
|
||||
|
||||
Workflow:
|
||||
1. Open `.scl` file in Neovim
|
||||
2. Test LSP features (hover, completion, go-to-definition)
|
||||
3. Verify diagnostics
|
||||
4. Test formatting
|
||||
5. Check workspace scanning
|
||||
|
||||
## LSP Implementation Notes
|
||||
|
||||
### Method Name Conversion
|
||||
LSP methods like `textDocument/didOpen` are converted to handler names like `textDocument_didOpen`:
|
||||
```lua
|
||||
local method_name = message.method:gsub("/", "_")
|
||||
local handler = handlers[method_name]
|
||||
```
|
||||
|
||||
### Request vs Notification
|
||||
- Requests have `id` field and require a response
|
||||
- Notifications have no `id` and should not receive a response
|
||||
```lua
|
||||
if message.id then
|
||||
-- Only send response for requests
|
||||
-- Request: send response
|
||||
return { id = message.id, result = result }
|
||||
end
|
||||
-- Notification: no response needed
|
||||
```
|
||||
|
||||
### Line Ending Handling
|
||||
The LSP server strips CRLF (`\r\n`) line endings for Windows compatibility:
|
||||
### Script Path Pattern
|
||||
```lua
|
||||
line = line:gsub("\r$", "")
|
||||
local script_path = debug.getinfo(1, "S").source:gsub("^@", ""):match("(.*/)") or ""
|
||||
if script_path == "" then
|
||||
script_path = "."
|
||||
end
|
||||
package.path = package.path .. ";" .. script_path .. "/?.lua"
|
||||
```
|
||||
|
||||
### JSON Parser
|
||||
The standalone JSON parser in `src/json.lua` handles:
|
||||
- Objects, arrays, strings, numbers, booleans, null
|
||||
- Escape sequences in strings
|
||||
- Whitespace skipping
|
||||
|
||||
Reference in New Issue
Block a user