diff --git a/README.md b/README.md index 54733f3d..4191e5e5 100644 --- a/README.md +++ b/README.md @@ -226,12 +226,50 @@ require("toggleterm").setup{ -- instead of next to each other -- default = 0 which means the feature is turned off horizontal_breakpoint = 135, - } + }, + navigation = { + enabled = false, -- enable file jumping under cursor in normal mode + use_picker = true, -- use s1n7ax/nvim-window-picker if installed + open_mapping = "gf", -- open file in target window + split_mapping = "gF", -- open file in split + direct_mapping = "gf", -- open directly in previous window without picker + split_direction = "vertical", -- "vertical" | "horizontal" + close_terminal = true, -- close/hide terminal after opening file + }, } ``` ### Usage +### File Navigation + +ToggleTerm can automatically detect file paths, line numbers, and column numbers under the cursor in normal mode (such as compiler errors, test failures, or log files) and jump directly to them: + +```lua +require("toggleterm").setup({ + navigation = { + enabled = true, + use_picker = true, -- uses s1n7ax/nvim-window-picker if installed + open_mapping = "gf", -- open in target window + split_mapping = "gF", -- open in split + direct_mapping = "gf", -- open in previous window without picker + split_direction = "vertical", -- "vertical" or "horizontal" + close_terminal = true, -- close/hide terminal after opening + }, +}) +``` + +Supported formats: +- `path/to/file:line:col` (e.g., `src/main.rs:42:15`) +- `path/to/file:line` (e.g., `src/main.rs:42`) +- `path/to/file` +- Python stack traces (`File "app.py", line 123`) +- Git diff paths (`a/file`, `b/file`) + +Commands: +- `:ToggleTermOpenFile` (opens file under cursor in target window) +- `:ToggleTermOpenFileSplit` (opens file under cursor in a split, accepts optional "horizontal" or "vertical") + ### `ToggleTerm` This is the command the mappings call under the hood. You can use it directly diff --git a/lua/toggleterm.lua b/lua/toggleterm.lua index bd03130c..286d47b1 100644 --- a/lua/toggleterm.lua +++ b/lua/toggleterm.lua @@ -490,6 +490,19 @@ local function setup_commands() set_term_name(opts.args, term) end end, { nargs = "?", count = true }) + + command("ToggleTermOpenFile", function() + require("toggleterm.navigation").open_file({ force_split = false }) + end, { desc = "ToggleTerm: open file under cursor in target window" }) + + command("ToggleTermOpenFileSplit", function(opts) + local dir = opts.args ~= "" and opts.args or nil + require("toggleterm.navigation").open_file({ force_split = true, split_direction = dir }) + end, { nargs = "?", desc = "ToggleTerm: open file under cursor in split (vertical or horizontal)" }) +end + +function M.open_file(opts) + require("toggleterm.navigation").open_file(opts) end function M.setup(user_prefs) diff --git a/lua/toggleterm/config.lua b/lua/toggleterm/config.lua index 736d8cf8..7ae64d5f 100644 --- a/lua/toggleterm/config.lua +++ b/lua/toggleterm/config.lua @@ -17,6 +17,15 @@ local function shade(color, factor) return colors.shade_color(color, factor) end --- @class Responsiveness --- @field horizontal_breakpoint number +--- @class FileNavigationOpts +--- @field enabled boolean +--- @field use_picker boolean? +--- @field open_mapping string? +--- @field split_mapping string? +--- @field direct_mapping string? +--- @field split_direction '"horizontal"' | '"vertical"'? +--- @field close_terminal boolean? + --- @class ToggleTermConfig --- @field size number --- @field shade_filetypes string[] @@ -41,6 +50,7 @@ local function shade(color, factor) return colors.shade_color(color, factor) end --- @field autochdir boolean --- @field title_pos '"left"' | '"center"' | '"right"' --- @field responsiveness Responsiveness +--- @field navigation FileNavigationOpts ---@type ToggleTermConfig local config = { @@ -72,6 +82,15 @@ local config = { responsiveness = { horizontal_breakpoint = 0, }, + navigation = { + enabled = false, + use_picker = true, + open_mapping = "gf", + split_mapping = "gF", + direct_mapping = "gf", + split_direction = "vertical", + close_terminal = true, + }, } ---Derive the highlights for a toggleterm and merge these with the user's preferences diff --git a/lua/toggleterm/navigation.lua b/lua/toggleterm/navigation.lua new file mode 100644 index 00000000..ee4369f5 --- /dev/null +++ b/lua/toggleterm/navigation.lua @@ -0,0 +1,188 @@ +local api = vim.api +local fn = vim.fn +local utils = require("toggleterm.utils") +local config = require("toggleterm.config") + +local M = {} + +---Extracts file path, line number, and column number under cursor or from a string +---@param line string? +---@param col number? +---@return string? file, number? lnum, number? colnr +function M.get_file_under_cursor(line, col) + line = line or api.nvim_get_current_line() + if not col then + local cursor = api.nvim_win_get_cursor(0) + col = cursor[2] + 1 + end + + local left = col + while left > 1 and not line:sub(left - 1, left - 1):match('[%s"\'`()%[%]<>"]') do + left = left - 1 + end + + local right = col + while right <= #line and not line:sub(right, right):match('[%s"\'`()%[%]<>"]') do + right = right + 1 + end + right = right - 1 + + if left > right then return nil end + + local token = line:sub(left, right):gsub("[,;:.]+$", "") + + -- Matcher file:line:col | file:line | file + local file, lnum, colnr = token:match("^(.-):(%d+):(%d+)$") + if not file then file, lnum = token:match("^(.-):(%d+)$") end + if not file then file = token end + + -- Format Python (ex: File "foo.py", line 42) + if not lnum then + local py_line = line:match("line%s+(%d+)") + if py_line then lnum = py_line end + end + + file = file:gsub('^["\']', ""):gsub('["\']$', "") + if file == "" then return nil end + + -- Clean git diff prefixes a/ or b/ if original file exists + if fn.filereadable(file) ~= 1 and file:match("^[ab]/") then + local stripped = file:sub(3) + if fn.filereadable(stripped) == 1 then file = stripped end + end + + return fn.expand(file), tonumber(lnum), tonumber(colnr) +end + +---Close or hide the active terminal if requested +local function close_terminal_if_needed() + local terms = require("toggleterm.terminal") + local termid = terms.get_focused_id and terms.get_focused_id() + if termid then + local current_tt = terms.get(termid) + if current_tt and current_tt:is_open() then + current_tt:close() + return + end + end + + local cur_buf = api.nvim_get_current_buf() + local cur_win = api.nvim_get_current_win() + for _, t in pairs(terms.get_all()) do + if (t.bufnr == cur_buf or t.window == cur_win) and t:is_open() then + t:close() + return + end + end + + if api.nvim_win_is_valid(cur_win) then + if api.nvim_win_get_config(cur_win).relative ~= "" then + api.nvim_win_close(cur_win, false) + return + end + end + + vim.cmd("hide") +end + +---Open file under cursor from terminal +---@param opts? { force_split?: boolean, use_picker?: boolean, close_terminal?: boolean, split_direction?: "horizontal" | "vertical" } +function M.open_file(opts) + opts = opts or {} + local file, lnum, colnr = M.get_file_under_cursor() + if not file or file == "" then + utils.notify("No valid file path detected under cursor", "warn") + return + end + + local conf = config.get().navigation or {} + local should_close = vim.F.if_nil(opts.close_terminal, conf.close_terminal) + + -- 1. Save previous window (wincmd p) + local prev_winnr = fn.winnr("#") + local prev_winid = prev_winnr > 0 and fn.win_getid(prev_winnr) or nil + + -- 2. Close / hide terminal if requested + if should_close then close_terminal_if_needed() end + + -- 3. Select target window + local target_win = nil + local use_picker = vim.F.if_nil(opts.use_picker, conf.use_picker) + local ok_wp, picker = pcall(require, "window-picker") + + if use_picker and ok_wp then + target_win = picker.pick_window({ + autoselect_one = true, + include_current_win = true, + filter_rules = { + bo = { + buftype = { "terminal", "quickfix", "nofile" }, + filetype = { "NvimTree", "neo-tree", "notify", "toggleterm" }, + }, + }, + }) + end + + if not target_win or not api.nvim_win_is_valid(target_win) then + if prev_winid and api.nvim_win_is_valid(prev_winid) then + target_win = prev_winid + else + target_win = api.nvim_get_current_win() + end + end + + api.nvim_set_current_win(target_win) + + -- 4. Open split if requested or if buffer is modified + local current_buf = api.nvim_win_get_buf(target_win) + local is_modified = vim.bo[current_buf].modified + + if opts.force_split or is_modified then + local split_direction = opts.split_direction or conf.split_direction or "vertical" + local split_cmd = split_direction == "horizontal" and "split" or "vsplit" + vim.cmd(split_cmd) + end + + -- 5. Open file + vim.cmd.edit(fn.fnameescape(file)) + + -- 6. Jump to line and col + if lnum then + local max_line = api.nvim_buf_line_count(0) + local target_line = math.min(lnum, max_line) + local target_col = math.max(0, (colnr or 1) - 1) + pcall(api.nvim_win_set_cursor, 0, { target_line, target_col }) + vim.cmd("normal! zz") + end +end + +---Setup buffer-local navigation keymaps +---@param bufnr number +---@param nav_conf FileNavigationOpts? +function M.setup_terminal_mappings(bufnr, nav_conf) + if not nav_conf or not nav_conf.enabled then return end + + if nav_conf.open_mapping then + utils.key_map("n", nav_conf.open_mapping, function() + M.open_file({ force_split = false, use_picker = nav_conf.use_picker }) + end, { buffer = bufnr, desc = "ToggleTerm: open file under cursor", silent = true }) + end + + if nav_conf.split_mapping then + utils.key_map("n", nav_conf.split_mapping, function() + M.open_file({ + force_split = true, + use_picker = nav_conf.use_picker, + split_direction = nav_conf.split_direction, + }) + end, { buffer = bufnr, desc = "ToggleTerm: open file under cursor in split", silent = true }) + end + + if nav_conf.direct_mapping then + utils.key_map("n", nav_conf.direct_mapping, function() + M.open_file({ force_split = false, use_picker = false }) + end, { buffer = bufnr, desc = "ToggleTerm: open file directly in previous window", silent = true }) + end +end + +return M diff --git a/lua/toggleterm/terminal.lua b/lua/toggleterm/terminal.lua index 19231c40..9fb59f37 100644 --- a/lua/toggleterm/terminal.lua +++ b/lua/toggleterm/terminal.lua @@ -143,6 +143,8 @@ local function setup_buffer_mappings(bufnr) if mapping and config.terminal_mappings then utils.key_map("t", mapping, "ToggleTerm", { buffer = bufnr, silent = true }) end + local nav = require("toggleterm.navigation") + nav.setup_terminal_mappings(bufnr, config.navigation) end ---@param id number terminal id diff --git a/tests/navigation_spec.lua b/tests/navigation_spec.lua new file mode 100644 index 00000000..6b1bce5f --- /dev/null +++ b/tests/navigation_spec.lua @@ -0,0 +1,56 @@ +local nav = require("toggleterm.navigation") + +describe("Navigation tests:", function() + describe("get_file_under_cursor parsing", function() + it("should parse file with line and column", function() + local line = "Error in src/main.lua:42:15: syntax error" + local col = 15 -- inside 'src/main.lua:42:15' + local file, lnum, colnr = nav.get_file_under_cursor(line, col) + assert.equal("src/main.lua", file) + assert.equal(42, lnum) + assert.equal(15, colnr) + end) + + it("should parse file with line only", function() + local line = "--> src/utils.lua:100" + local col = 10 + local file, lnum, colnr = nav.get_file_under_cursor(line, col) + assert.equal("src/utils.lua", file) + assert.equal(100, lnum) + assert.is_nil(colnr) + end) + + it("should parse plain file without line/column", function() + local line = "opening config/nvim/init.lua now" + local col = 15 + local file, lnum, colnr = nav.get_file_under_cursor(line, col) + assert.equal("config/nvim/init.lua", file) + assert.is_nil(lnum) + assert.is_nil(colnr) + end) + + it("should parse Python traceback format", function() + local line = ' File "app.py", line 42, in my_func' + local col = 12 + local file, lnum = nav.get_file_under_cursor(line, col) + assert.equal("app.py", file) + assert.equal(42, lnum) + end) + + it("should handle brackets and parentheses delimiters", function() + local line = "([src/parser.lua:25:3]) failed" + local col = 6 + local file, lnum, colnr = nav.get_file_under_cursor(line, col) + assert.equal("src/parser.lua", file) + assert.equal(25, lnum) + assert.equal(3, colnr) + end) + + it("should return nil when cursor is on whitespace or empty line", function() + local line = " " + local col = 2 + local file = nav.get_file_under_cursor(line, col) + assert.is_nil(file) + end) + end) +end)