### Install Semshi with lazy.nvim Source: https://github.com/wookayin/semshi/blob/master/README.md Configure lazy.nvim to install Semshi. This example includes optional initialization for custom settings like disabling error signs. ```lua { "wookayin/semshi", build = ":UpdateRemotePlugins", version = "*", -- Recommended to use the latest release init = function() vim.g['semshi#error_sign'] = false end, config = function() -- any config or setup that would need to be done after plugin loading end, } ``` -------------------------------- ### Install Semshi with lazy.nvim Source: https://context7.com/wookayin/semshi/llms.txt Configure lazy.nvim to install Semshi and set initial configuration options. Options set in init take effect before the plugin loads. ```lua -- ~/.config/nvim/lua/plugins/semshi.lua { "wookayin/semshi", build = ":UpdateRemotePlugins", version = "*", -- always use the latest release tag init = function() -- Options set here take effect before the plugin loads vim.g['semshi#error_sign'] = false -- disable sign-column error marker vim.g['semshi#mark_selected_nodes'] = 2 -- also highlight the node under cursor vim.g['semshi#update_delay_factor'] = 0.0001 -- throttle in large files end, } ``` -------------------------------- ### Install Semshi with vim-plug Source: https://context7.com/wookayin/semshi/llms.txt Use vim-plug to install Semshi and register its remote plugin manifest. Remember to run :UpdateRemotePlugins after installation or updates. ```vim " ~/.config/nvim/init.vim Plug 'wookayin/semshi', { 'do': ':UpdateRemotePlugins', 'tag': '*' } ``` ```vim " After editing init.vim: :PlugInstall :UpdateRemotePlugins " must run whenever the plugin is installed or updated ``` -------------------------------- ### Install Python Provider for Semshi Source: https://github.com/wookayin/semshi/blob/master/README.md Ensure you have Neovim with Python 3 support and install the pynvim package. This command upgrades the provider for Python 3. ```bash python3 -m pip install pynvim --upgrade ``` -------------------------------- ### Instantiate Parser and Perform Full Parse Source: https://context7.com/wookayin/semshi/llms.txt Initialize the Parser with optional excluded highlight groups and a syntax-fix flag. Perform an initial parse to get all added and removed nodes. ```python from semshi.parser import Parser parser = Parser( exclude=['local'], # don't emit nodes for these hl groups fix_syntax=True, # attempt to tolerate minor transient syntax errors ) code_v1 = """ import os def greet(name, unused_arg): msg = "Hello, " + name return msg """ # First parse – all nodes are "added" added, removed = parser.parse(code_v1) print(f"tick={parser.tick}, +{len(added)} nodes, -{len(removed)} nodes") # e.g.: tick=1, +7 nodes, -0 nodes for node in added: print(node) # # # # ← detected as unused # # # ``` -------------------------------- ### Install Semshi with vim-plug Source: https://github.com/wookayin/semshi/blob/master/README.md Add Semshi to your vim-plug configuration and run :PlugInstall. The 'do' option ensures remote plugins are updated. ```vim Plug 'wookayin/semshi', { 'do': ':UpdateRemotePlugins', 'tag': '*' } ``` -------------------------------- ### Get Locations by Highlight Group Source: https://context7.com/wookayin/semshi/llms.txt Find the locations of all nodes associated with a specific highlight group, such as `IMPORTED`, using `parser.locations_by_hl_group`. ```python from semshi.node import IMPORTED locs = parser.locations_by_hl_group(IMPORTED) print(locs) # [(1, 7)] ``` -------------------------------- ### Get Locations by Node Type Source: https://context7.com/wookayin/semshi/llms.txt Retrieve the locations of all class or function definitions using `parser.locations_by_node_types` with AST node types. ```python import ast locs = parser.locations_by_node_types([ast.FunctionDef, ast.AsyncFunctionDef]) print(locs) # [(3, 0)] ``` -------------------------------- ### Vim Key Mappings for Semshi Operations Source: https://context7.com/wookayin/semshi/llms.txt Recommended key mappings for common Semshi operations like renaming symbols, navigating between occurrences, jumping to definitions, and handling errors. ```vim " ~/.config/nvim/init.vim " Rename symbol under cursor nmap rr :Semshi rename " Navigate between all occurrences of the name under cursor nmap :Semshi goto name next nmap

:Semshi goto name prev " Jump between class definitions nmap c :Semshi goto class next nmap C :Semshi goto class prev " Jump between function definitions nmap f :Semshi goto function next nmap F :Semshi goto function prev " Jump to first unresolved name / first unused parameter nmap gu :Semshi goto unresolved first nmap gp :Semshi goto parameterUnused first " Show / jump to syntax error nmap ee :Semshi error nmap ge :Semshi goto error ``` -------------------------------- ### :Semshi error / goto error Source: https://context7.com/wookayin/semshi/llms.txt Inspect or navigate to the current syntax error in the buffer. ```APIDOC ## :Semshi error / goto error ### Description Inspect or navigate to the current syntax error. ### Commands - `:Semshi error` - Prints the syntax error message and location. - `:Semshi goto error` - Moves the cursor to the error location. ``` -------------------------------- ### :Semshi goto Source: https://context7.com/wookayin/semshi/llms.txt Navigate between symbols, definitions, or highlight groups within the code. ```APIDOC ## :Semshi goto ### Description Jump to Names, Functions, Classes, or Highlight Groups. ### Usage - Navigate between all occurrences of the name under the cursor: `:Semshi goto name next` `:Semshi goto name prev` `:Semshi goto name first` `:Semshi goto name last` - Jump to class / function definitions: `:Semshi goto class next` `:Semshi goto function prev` `:Semshi goto function first` - Jump to nodes by highlight group: `:Semshi goto unresolved first` `:Semshi goto parameterUnused first` `:Semshi goto imported next` Available groups: local, unresolved, attribute, builtin, free, global, parameter, parameterUnused, self, imported ``` -------------------------------- ### Vim Commands for Semshi Navigation by Name, Function, Class, or Highlight Group Source: https://context7.com/wookayin/semshi/llms.txt Navigate between occurrences of a name, jump to function or class definitions, or move between nodes based on highlight groups like 'unresolved' or 'parameterUnused'. ```vim " Navigate between all occurrences of the name under the cursor: :Semshi goto name next :Semshi goto name prev :Semshi goto name first :Semshi goto name last " Jump to class / function definitions: :Semshi goto class next :Semshi goto function prev :Semshi goto function first " Jump to nodes by highlight group: :Semshi goto unresolved first " first unresolved name :Semshi goto parameterUnused first " first unused parameter :Semshi goto imported next " next imported name " Available groups: local, unresolved, attribute, builtin, free, " global, parameter, parameterUnused, self, imported ``` -------------------------------- ### Traverse AST and Symbol Table with Visitor Source: https://context7.com/wookayin/semshi/llms.txt Use the `visitor` function to traverse a pre-built AST and symtable, emitting a list of `Node` objects. This function handles Python scoping rules and attribute detection. Ensure `semshi.util.code_to_lines` is used to convert code to lines for accurate line-based analysis. ```python import ast import symtable from semshi.visitor import visitor from semshi.util import code_to_lines code = """ from pathlib import Path def read_file(path: Path, encoding: str = "utf-8") -> str: with open(path, encoding=encoding) as fh: return fh.read() """ lines = code_to_lines(code) ast_root = ast.parse(code) sym_root = symtable.symtable(code, '', 'exec') nodes = visitor(lines, sym_root, ast_root) for n in nodes: print(f"{n.name!r:12s} → {n.hl_group[6:]}") # strip 'semshi' prefix ``` -------------------------------- ### Access Highlight Group Mappings Source: https://context7.com/wookayin/semshi/llms.txt The `hl_groups` dictionary provides a mapping from short highlight group names used internally to their corresponding Neovim highlight group strings. ```python # The hl_groups dict maps short names to Neovim highlight group strings print(hl_groups) # {'unresolved': 'semshiUnresolved', 'attribute': 'semshiAttribute', ...} ``` -------------------------------- ### BufferHandler API for Neovim Integration Source: https://context7.com/wookayin/semshi/llms.txt The `BufferHandler` class manages Neovim buffer highlights, viewport, and incremental updates. It provides methods for updating highlights, marking selected names, navigating nodes, renaming, and managing syntax errors. This is primarily an internal API used by the `Plugin` class. ```python # This is internal API used by the Plugin class; shown for documentation purposes. # BufferHandler is created once per buffer by Plugin._select_handler(). # Conceptual lifecycle: # # handler = BufferHandler(buf, vim, options) # # # Called on every text change (async, starts/schedules update thread): # handler.update(force=False, sync=False) # # # Called on every cursor move (marks peers of the name under cursor): # handler.mark_selected(cursor=(line, col)) # # # Called when the visible window region changes: # handler.viewport(start=1, stop=40) # # # Scope-aware rename at cursor: # handler.rename(cursor=(line, col), new_name="new_name") # # # Navigate to next/prev/first/last node of a given type: # handler.goto("name", "next") # handler.goto("function", "prev") # handler.goto("class", "first") # handler.goto("unresolved", "last") # handler.goto("error") # jump to syntax error # # # Echo the current syntax error message: # handler.show_error() # # # Clear all Semshi highlights from the buffer: # handler.clear_highlights() # # # Current syntax error (SyntaxError | None): # err = handler.syntax_error # # # Graceful shutdown (cancels pending timers so Neovim exits cleanly): # handler.shutdown() ``` -------------------------------- ### VimL Mappings for Semshi Commands Source: https://github.com/wookayin/semshi/blob/master/README.md These VimL mappings provide convenient shortcuts for various Semshi commands, such as renaming, navigating code elements, and error handling. ```VimL nmap rr :Semshi rename ``` ```VimL nmap :Semshi goto name next ``` ```VimL nmap

:Semshi goto name prev ``` ```VimL nmap c :Semshi goto class next ``` ```VimL nmap C :Semshi goto class prev ``` ```VimL nmap f :Semshi goto function next ``` ```VimL nmap F :Semshi goto function prev ``` ```VimL nmap gu :Semshi goto unresolved first ``` ```VimL nmap gp :Semshi goto parameterUnused first ``` ```VimL nmap ee :Semshi error ``` ```VimL nmap ge :Semshi goto error ``` -------------------------------- ### Vim Commands for Semshi Error Inspection and Navigation Source: https://context7.com/wookayin/semshi/llms.txt Inspect syntax errors or navigate directly to their location. The `error` command prints the error message, while `goto error` moves the cursor. ```vim :Semshi error " prints: Syntax error: invalid syntax (12, 5) :Semshi goto error " moves cursor to the error location ``` -------------------------------- ### Vim Commands for Semshi Activation Control Source: https://context7.com/wookayin/semshi/llms.txt Control Semshi's activation state for the current buffer. Use these commands to enable, disable, toggle, or pause highlighting. ```vim :Semshi enable " attach event listeners, start highlighting :Semshi disable " stop highlighting and clear all highlights :Semshi toggle " enable if disabled, disable if enabled :Semshi pause " detach listeners but leave existing highlights in place ``` -------------------------------- ### Vim Command for Semshi Status Information Source: https://context7.com/wookayin/semshi/llms.txt Print diagnostic information about the current buffer's Semshi state, including handler status and syntax error details. ```vim :Semshi status " Output example: " Semshi is attached on (bufnr=3) " - current handler: " - handlers: {3: } " - syntax error: (none) ``` -------------------------------- ### Node ID for Highlighting Source: https://context7.com/wookayin/semshi/llms.txt Each node has a unique ID, which is used as the source ID (`src_id`) for highlighting in Neovim. ```python # Node id is unique and used as the Neovim buffer highlight src_id print(node.id) # e.g., 314001 ``` -------------------------------- ### Configure Deoplete Auto-Completion Delay (Older Versions) Source: https://github.com/wookayin/semshi/blob/master/README.md For older versions of Deoplete (<= 5.2), use this alternative method to set the auto-complete delay. ```VimL let g:deoplete#auto_complete_delay = 100 ``` -------------------------------- ### Vim Commands for Semshi Highlighting and Clearing Source: https://context7.com/wookayin/semshi/llms.txt Force a full re-parse and highlight update, or remove all Semshi highlights from the current buffer. ```vim :Semshi highlight " force a full synchronous re-parse and highlight update :Semshi clear " remove all Semshi highlights from the current buffer ``` -------------------------------- ### :Semshi enable / disable / toggle / pause Source: https://context7.com/wookayin/semshi/llms.txt Control Semshi's activation state for the current buffer. These commands allow users to enable, disable, toggle, or pause Semshi's highlighting and analysis features. ```APIDOC ## :Semshi enable / disable / toggle / pause ### Description Control Semshi's activation state for the current buffer. ### Commands - `:Semshi enable` - Attach event listeners and start highlighting. - `:Semshi disable` - Stop highlighting and clear all highlights. - `:Semshi toggle` - Enable if disabled, disable if enabled. - `:Semshi pause` - Detach listeners but leave existing highlights in place. ``` -------------------------------- ### Vim Highlight Groups for Semshi Source: https://context7.com/wookayin/semshi/llms.txt Define or override Semshi's default highlight groups. Customizations should be applied after Semshi initialization, typically within a FileType autocmd. ```vim " Default colors (optimized for dark backgrounds) hi semshiLocal ctermfg=209 guifg=#ff875f hi semshiGlobal ctermfg=214 guifg=#ffaf00 hi semshiImported ctermfg=214 guifg=#ffaf00 cterm=bold gui=bold hi semshiParameter ctermfg=75 guifg=#5fafff hi semshiParameterUnused ctermfg=117 guifg=#87d7ff cterm=underline gui=underline hi semshiFree ctermfg=218 guifg=#ffafd7 hi semshiBuiltin ctermfg=207 guifg=#ff5fff hi semshiAttribute ctermfg=49 guifg=#00ffaf hi semshiSelf ctermfg=249 guifg=#b2b2b2 hi semshiUnresolved ctermfg=226 guifg=#ffff00 cterm=underline gui=underline hi semshiSelected ctermfg=231 guifg=#ffffff ctermbg=161 guibg=#d7005f hi semshiErrorSign ctermfg=231 guifg=#ffffff ctermbg=160 guibg=#d70000 hi semshiErrorChar ctermfg=231 guifg=#ffffff ctermbg=160 guibg=#d70000 " Custom overrides that survive colorscheme switches: function! MyCustomHighlights() hi semshiGlobal ctermfg=red guifg=#ff0000 hi semshiParameter ctermfg=81 guifg=#5fd7ff endfunction autocmd FileType python call MyCustomHighlights() autocmd ColorScheme * call MyCustomHighlights() ``` -------------------------------- ### Configure Deoplete Auto-Completion Delay Source: https://github.com/wookayin/semshi/blob/master/README.md If Semshi is slow when used with deoplete.nvim, increase the auto-complete delay to prevent completion triggers from blocking Semshi's highlighting. ```VimL call deoplete#custom#option('auto_complete_delay', 100) ``` -------------------------------- ### Inspect Node Properties Source: https://context7.com/wookayin/semshi/llms.txt Iterate through parsed nodes to inspect properties like name, highlight group, line number, column, and end position. This helps understand the structure and semantics of the code. ```python from semshi.parser import Parser from semshi.node import ( LOCAL, GLOBAL, IMPORTED, PARAMETER, PARAMETER_UNUSED, BUILTIN, FREE, ATTRIBUTE, SELF, UNRESOLVED, SELECTED, hl_groups, ) parser = Parser() code = """ import sys CONSTANT = 42 class MyClass: def method(self, value, unused): self.data = value result = len(sys.argv) return result """ added, _ = parser.parse(code) # Inspect every node's properties for node in added: print( f" name={node.name!r:20s}" f" hl_group={node.hl_group!r:30s}" f" line={node.lineno} col={node.col} end={node.end}" ) # name='sys' hl_group='semshiImported' line=1 col=7 end=10 # name='CONSTANT' hl_group='semshiGlobal' line=3 col=0 end=8 # name='MyClass' hl_group='semshiGlobal' line=5 col=6 end=13 # name='method' hl_group='semshiGlobal' line=6 col=8 end=14 # name='self' hl_group='semshiSelf' line=6 col=15 end=19 # name='value' hl_group='semshiParameter' line=6 col=21 end=26 # name='unused' hl_group='semshiParameterUnused' line=6 col=28 end=34 # name='data' hl_group='semshiAttribute' line=7 col=13 end=17 # name='value' hl_group='semshiParameter' line=7 col=20 end=25 # name='result' hl_group='semshiLocal' line=8 col=8 end=14 # name='len' hl_group='semshiBuiltin' line=8 col=17 end=20 # name='sys' hl_group='semshiImported' line=8 col=21 end=24 # name='result' hl_group='semshiLocal' line=9 col=15 end=21 ``` -------------------------------- ### Configure Semshi Options in Vimscript Source: https://context7.com/wookayin/semshi/llms.txt Set various Semshi configuration options using Vimscript global variables. These options control features like automatic activation, excluded highlight groups, and node marking. ```vim " ~/.config/nvim/init.vim (Vimscript example showing all options) " File types on which Semshi activates automatically (default: ['python']) let g:semshi#filetypes = ['python'] " Highlight groups to suppress. 'local' is excluded by default for performance. " Full list: local, unresolved, attribute, builtin, free, global, " parameter, parameterUnused, self, imported let g:semshi#excluded_hl_groups = ['local'] " 0 = no marking, 1 = mark same-scope peers, 2 = also mark node under cursor let g:semshi#mark_selected_nodes = 1 " Suppress Vim's own builtin/exception highlights (Semshi handles them) let g:semshi#no_default_builtin_highlight = v:true " Bind most non-Semshi Python syntax to pythonStatement for less visual noise let g:semshi#simplify_markup = v:true " Show 'E>' sign in the sign column on syntax errors let g:semshi#error_sign = v:true " Seconds to wait before showing the error sign (avoids flicker while typing) let g:semshi#error_sign_delay = 1.5 " Force a full highlight refresh on every keystroke (higher overhead) let g:semshi#always_update_all_highlights = v:false " Attempt to keep highlights valid even when there is a temporary syntax error let g:semshi#tolerate_syntax_errors = v:true " Delay factor per line: updates wait (factor × #lines) seconds. " Good starting value for large files: 0.0001 let g:semshi#update_delay_factor = 0.0 " When cursor is on `self`, resolve to the attribute (self.foo → foo) let g:semshi#self_to_attribute = v:true ``` -------------------------------- ### Python Parser API for Semshi Source: https://context7.com/wookayin/semshi/llms.txt Utilize the `semshi.parser.Parser` class for standalone analysis of Python source code. It builds an AST and symbol table, returning node deltas between parses. ```python from semshi.parser import Parser, UnparsableError ``` -------------------------------- ### Define Custom Semshi Highlights Source: https://github.com/wookayin/semshi/blob/master/README.md Customize Semshi highlight groups by defining them in a function and calling it after a colorscheme is loaded. This ensures your custom highlights persist across colorscheme changes. ```VimL function MyCustomHighlights() hi semshiGlobal ctermfg=red guifg=#ff0000 endfunction autocmd FileType python call MyCustomHighlights() ``` ```VimL autocmd ColorScheme * call MyCustomHighlights() ``` -------------------------------- ### :Semshi highlight / clear Source: https://context7.com/wookayin/semshi/llms.txt Force a re-parse and highlight update or clear all Semshi highlights from the current buffer. ```APIDOC ## :Semshi highlight / clear ### Description Force a full synchronous re-parse and highlight update, or remove all Semshi highlights from the current buffer. ### Commands - `:Semshi highlight` - Force a full synchronous re-parse and highlight update. - `:Semshi clear` - Remove all Semshi highlights from the current buffer. ``` -------------------------------- ### Perform Incremental Parse Source: https://context7.com/wookayin/semshi/llms.txt After an initial parse, modify the code slightly and perform an incremental parse. Semshi detects minor changes and diffs only the affected lines. ```python code_v2 = code_v1.replace('"Hello, "', '"Hi, "') # single-line change # Incremental parse – Semshi detects a minor change and diffs only that line added2, removed2 = parser.parse(code_v2) print(f"+{len(added2)} nodes, -{len(removed2)} nodes") # Typically: +0 nodes, -0 nodes (same nodes, content on same line unchanged in identity) ``` -------------------------------- ### Node Position Shorthand Source: https://context7.com/wookayin/semshi/llms.txt Access the position of a node (line number and column) as a tuple using the `.pos` attribute. ```python # Node position shorthand node = added[0] # 'sys' print(node.pos) # (1, 7) — (lineno, col) ``` -------------------------------- ### :Semshi rename [new_name] Source: https://context7.com/wookayin/semshi/llms.txt Perform a scope-aware rename of the symbol under the cursor. This command can be used interactively or with a direct new name. ```APIDOC ## :Semshi rename [new_name] ### Description Scope-aware rename of the symbol under the cursor. All occurrences in the same scope are renamed atomically. ### Usage - Interactive prompt (asks for new name): `:Semshi rename` - Direct rename (no prompt): `:Semshi rename new_variable_name` Output: "3 nodes renamed." ``` -------------------------------- ### Handle Syntax Errors Source: https://context7.com/wookayin/semshi/llms.txt Use a try-except block to catch `UnparsableError` when parsing code with syntax errors. Access the last syntax error using `parser.syntax_errors`. ```python from semshi.parser import UnparsableError try: parser.parse("def foo(: pass ") except UnparsableError as e: print("Unrecoverable:", e.error) # Unrecoverable: invalid syntax (, line 1) # Current syntax error (most recent) print(parser.syntax_errors[-1]) # SyntaxError or None ``` -------------------------------- ### Default Semshi Highlight Groups Source: https://github.com/wookayin/semshi/blob/master/README.md These are the default highlight groups defined by Semshi. They are best viewed on dark backgrounds and can be customized in your vimrc. ```VimL hi semshiLocal ctermfg=209 guifg=#ff875f hi semshiGlobal ctermfg=214 guifg=#ffaf00 hi semshiImported ctermfg=214 guifg=#ffaf00 cterm=bold gui=bold hi semshiParameter ctermfg=75 guifg=#5fafff hi semshiParameterUnused ctermfg=117 guifg=#87d7ff cterm=underline gui=underline hi semshiFree ctermfg=218 guifg=#ffafd7 hi semshiBuiltin ctermfg=207 guifg=#ff5fff hi semshiAttribute ctermfg=49 guifg=#00ffaf hi semshiSelf ctermfg=249 guifg=#b2b2b2 hi semshiUnresolved ctermfg=226 guifg=#ffff00 cterm=underline gui=underline hi semshiSelected ctermfg=231 guifg=#ffffff ctermbg=161 guibg=#d7005f hi semshiErrorSign ctermfg=231 guifg=#ffffff ctermbg=160 guibg=#d70000 hi semshiErrorChar ctermfg=231 guifg=#ffffff ctermbg=160 guibg=#d70000 sign define semshiError text=E> texthl=semshiErrorSign ``` -------------------------------- ### Find Nodes in Same Scope Source: https://context7.com/wookayin/semshi/llms.txt Use `parser.same_nodes(node)` to retrieve all nodes that share the same scope as the provided node. ```python # All nodes sharing the same scope as node_at result for peer in parser.same_nodes(node): print(peer) ``` -------------------------------- ### Find Node at Cursor Position Source: https://context7.com/wookayin/semshi/llms.txt Use `parser.node_at((line, col))` to find the specific node at a given cursor position (1-based line number). ```python # Find the node at a given (line, col) cursor position (1-based line) node = parser.node_at((3, 4)) # line 3, col 4 → 'greet' print(node) # ``` -------------------------------- ### Vim Command for Semshi Symbol Renaming Source: https://context7.com/wookayin/semshi/llms.txt Perform scope-aware renaming of the symbol under the cursor. This command can be used interactively or with a direct new name. ```vim " Interactive prompt (asks for new name): :Semshi rename " Direct rename (no prompt): :Semshi rename new_variable_name " Output: "3 nodes renamed." ``` -------------------------------- ### :Semshi status Source: https://context7.com/wookayin/semshi/llms.txt Print diagnostic information about the current buffer's Semshi state. ```APIDOC ## :Semshi status ### Description Print diagnostic information about the current buffer's Semshi state. ### Command `:Semshi status` ### Output Example Semshi is attached on (bufnr=3) - current handler: - handlers: {3: } - syntax error: (none) ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.