How theprimeagen/harpoon works
Main Components
• Core Library – This is the heart of the plugin that handles configuration (via the setup function), global settings, and the common utilities (lua/harpoon/utils.lua).
• Management – Contained in lua/harpoon/mark.lua, this manages marks (i.e., saving file positions and related metadata) and acts as the interface to add or retrieve file marks.
• User Interface (UI) – Found in lua/harpoon/ui.lua, this module handles the display of a quick menu that allows users to navigate through marked files.
• Terminal Management – lua/harpoon/term.lua handles the creation, navigation (gotoTerminal), and sending commands to persistent terminal sessions.
• Command UI – Lua/harpoon/cmd-ui.lua provides an interface for preconfiguring and sending commands to terminals.
• Tmux Integration – lua/harpoon/tmux.lua ensures that terminal operations can work seamlessly with tmux (e.g., switching windows, sending commands, etc.), supported further by dedicated scripts (scripts/tmux/…).
• Telescope Extension – Under lua/telescope/_extensions (harpoon.lua and marks.lua), these modules register Harpoon with Telescope so that users can navigate marks via Telescope’s fuzzy finder.
• Tests – The tests under lua/harpoon/test help validate core functionalities and interactions between the components.
Relationships and Interactions
• The Core Library interacts with all modules: it initializes the plugin with setup({…}) and provides global configuration.
• The Mark Management module is invoked by both the UI (for displaying available marks) and by developers using commands (e.g., to add a file).
• The UI module gathers the list of marks from the Mark Management module and lets users select a file to navigate to.
• Terminal Management and Tmux Integration form a pair. When a user sends a command (via the Command UI or directly) or navigates to a terminal, Terminal Management will either create or switch context; if tmux support is enabled, it routes the command via Tmux Integration.
• The Telescope Extension interfaces with core Harpoon functionalities (especially Marks) to integrate with the fuzzy finder provided by Telescope.
Architectural Patterns and Principles
• Modular Design: Each major functionality (marks, ui, terminal, tmux, telescope extension) is implemented as a separate Lua module.
• Separation of Concerns: UI, state management, and terminal/tmux logic are clearly separated to allow easier maintenance and possible future extensions.
• Extensibility: The plugin is designed in a way that additional features (like new Telescope extensions) can be easily added.
• Testability: The inclusion of test files in lua/harpoon/test indicates an emphasis on verifying each component.