From 7d54578406a36f02b0e69141ae9db6a64be5b07b Mon Sep 17 00:00:00 2001 From: Lazar Bulovan Date: Tue, 17 Feb 2026 15:30:30 +0100 Subject: [PATCH] docs: Update AGENTS.md with comprehensive feature documentation --- AGENTS.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 112 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 88c9924..f187784 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,8 +9,18 @@ The unified `scl_lsp` project provides: - **Linter** - Diagnostics and code validation - **Formatter** - Document formatting - **Syntax Highlighting** - Tree-sitter based -- **Auto-completion** - blink.cmp integration +- **Auto-completion** - blink.cmp integration with smart context-aware completions - **Auto-prefix** - Automatic `#` prefixing for variables +- **Workspace Scanning** - Automatic scanning of UDTs (.udt) and Global DBs (.db) + +## Reference Project for Testing + +For testing and referencing SCL, UDT, DB, and XML files, use the reference project at: +``` +~/dev/siemens/projects/scl_lang_support_lazyvim_ref_project +``` + +This project contains example SCL files, UDT definitions, and global data blocks. ## Project Structure @@ -19,25 +29,27 @@ scl_lsp/ ├── src/ # LSP server implementation │ ├── main.lua # Entry point, protocol handling │ ├── parser.lua # Regex-based SCL parser -│ ├── treesitter.lua # Tree-sitter integration -│ ├── diagnostics.lua # Linter diagnostics -│ ├── formatter.lua # Document formatter -│ ├── json.lua # JSON encoder/decoder -│ └── plc_json.lua # External UDT loading +│ ├── treesitter.lua # Tree-sitter integration +│ ├── diagnostics.lua # Linter diagnostics +│ ├── formatter.lua # Document formatter +│ ├── json.lua # JSON encoder/decoder +│ └── plc_json.lua # External UDT loading ├── lua/ -│ ├── scl/ # Neovim plugin modules (from scl_syntax_nvim) -│ │ ├── init.lua -│ │ ├── auto_prefix.lua -│ │ ├── blink_cmp_source.lua -│ │ ├── fb_parser.lua -│ │ ├── udt_parser.lua -│ │ ├── variables.lua -│ │ └── workspace_types.lua +│ ├── scl/ # Neovim plugin modules +│ │ ├── init.lua # Main plugin setup +│ │ ├── auto_prefix.lua # Auto-prefix variables with # +│ │ ├── blink_cmp_source.lua # blink.cmp completion source +│ │ ├── db_parser.lua # Global DB (.db) parser +│ │ ├── fb_parser.lua # Function Block parser +│ │ ├── udt_parser.lua # UDT (.udt) parser +│ │ ├── variables.lua # Local variable extraction +│ │ ├── workspace_types.lua # Workspace scanning (UDTs, DBs, FBs) +│ │ └── multiline_params.lua # Multiline parameter filling │ └── scl_lsp/ -│ ├── init.lua # Unified plugin setup +│ ├── init.lua # Unified plugin setup │ └── plugins/ -│ └── scl.lua # LazyVim plugin spec -├── queries/ # Tree-sitter queries +│ └── scl.lua # LazyVim plugin spec +├── queries/ # Tree-sitter queries │ ├── highlights.scm │ ├── indents.scm │ ├── folds.scm @@ -47,6 +59,77 @@ scl_lsp/ └── tree-sitter.json # Parser config ``` +## Key Modules + +### Parser Modules + +| Module | Purpose | +|--------|---------| +| `udt_parser.lua` | Parses `.udt` files to extract TYPE definitions and STRUCT members | +| `db_parser.lua` | Parses `.db` files to extract DATA_BLOCK definitions and VAR members | +| `fb_parser.lua` | Parses `.scl` files to extract FUNCTION_BLOCK and FUNCTION interfaces | +| `variables.lua` | Extracts local variables from VAR sections | + +### Completion System + +| Module | Purpose | +|--------|---------| +| `blink_cmp_source.lua` | Main completion source for blink.cmp. Handles: | +| | - Local variables (with # prefix after BEGIN) | +| | - UDT types (quoted: "MyUDT") | +| | - UDT members (after dot: #var.member) | +| | - Global DB names (available in general completion) | +| | - Global DB members (after quote+dot: "DBName".member) | +| | - FB parameter completions (inside FB calls) | +| | - Basic SCL types | + +### Workspace Scanner + +| Module | Purpose | +|--------|---------| +| `workspace_types.lua` | Scans project for: | +| | - `.udt` files (UDT types) | +| | - `.db` files (Global Data Blocks) | +| | - `.scl` files (Function Blocks/Functions) | +| | - Uses project markers to find project root | + +## Auto-Completion Features + +### Trigger Characters +- `#` - Local variables (after BEGIN) +- `.` - Member access (UDT/DB members) +- `"` - Global DB names and member access +- `(` - FB/Function parameter completion +- ` ` (space) - General completion (variables, UDTs, DBs, types) + +### Completion Contexts + +1. **Variable Completion** (after space or at start) + - Local variables from VAR sections + - UDT type names (quoted) + - Global DB names (wrapped in quotes automatically) + - Basic SCL types + +2. **Member Completion** (after `.`) + - UDT members (resolves through nested types) + - DB members (resolves through nested types) + - Supports multi-level nesting: `#var.member.submember` + +3. **Global DB Completion** + - Type `"` then select DB → shows DB members + - Or type space → select DB from list → automatically wrapped in quotes + +4. **FB Parameter Completion** (after `fbName(`) + - Input parameters (`:=`) + - InOut parameters (`:=`) + - Output parameters (`=>`) + +### Special Features + +- **Auto-Prefix**: Adds `#` to variables automatically after BEGIN +- **Quote Wrapping**: DB names selected from general completion are automatically wrapped in quotes +- **Nested Resolution**: Multi-level member path resolution for both UDTs and DBs + ## Development ### Running the LSP Server @@ -84,3 +167,15 @@ tree-sitter parse corpus/test/main_org_block.scl ## Configuration See `README.md` for configuration options and usage. + +## 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/ |