feat: Bracketed Paste for Terminal Line Sending

[001ben]

This PR adds bracketed paste functionality to the terminal line sending feature, particularly beneficial for REPLs of whitespace-sensitive languages like Python. For additional context, please see conrad irwin's blog page: https://cirw.in/blog/bracketed-paste

Problem

When sending multiple lines of code to a REPL (like IPython), the default behavior can lead to incorrect execution due to inconsistent indentation or premature code evaluation.

For example, a function with whitespace partway through will execute before reading the rest of the function.

def my_function():
    print("This is the first part")
    
    print("This is the second part")
    
    return "Done"

# Without bracketed paste, this might execute prematurely after the first print statement

Solution

Implemented bracketed paste mode for sending lines to the terminal. This approach wraps the sent text in special escape sequences, signaling the receiving program to treat the input as a single paste operation.

Key benefits:

• Preserves indentation and formatting of multi-line code blocks
• Prevents premature execution of partial code snippets
• Improves reliability when working with whitespace-sensitive languages

Implementation Details

• Added a new argument to toggleterm.lua exec to enable bracketed paste mode
• Modified the line sending function Terminal:send to include bracketed paste escape sequences when use_bracketed_paste is true
• Modified the send_line_to_terminal function to include bracketed paste escape sequences when use_bracketed_paste is true
• Tested functionality with IPython REPL, ensuring correct handling of multi-line Python code blocks

Usage

Users can enable bracketed paste mode when sending lines to the terminal:

require('toggleterm').setup({})

-- In your keymaps or wherever you call send_lines_to_terminal
require('toggleterm').send_lines_to_terminal(
  "visual",  -- or "current" or "line"
  true,      -- trim_spaces
  {},        -- cmd_data (empty table if not needed)
  true       -- use_bracketed_paste
)

This allows users to selectively use bracketed paste mode when needed, while maintaining compatibility with existing configurations.

The current "Sending lines to the terminal" docs example would be updated from:

    local trim_spaces = true
    vim.keymap.set("v", "<space>s", function()
        require("toggleterm").send_lines_to_terminal("single_line", trim_spaces, { args = vim.v.count })
    end)

to

    local trim_spaces = true
    local use_bracketed_paste = true
    vim.keymap.set("v", "<space>s", function()
        require("toggleterm").send_lines_to_terminal("single_line", trim_spaces, { args = vim.v.count }, use_bracketed_paste)
    end)

Impact

This enhancement significantly improves the user experience when working with REPLs, particularly for languages like Python, where indentation is crucial. It allows for more reliable and predictable code execution within the Neovim terminal integration.

Testing

• Manually tested with various Python code snippets in IPython REPL
• Added a unit test in tests/terminal_spec.lua

All feedback is welcome!

[vandalt]

Thanks for the PR, started using it today for testing and it helps a lot when working with IPython. Let me know if you need testing on specific things :)

[mohelm]

@akinsho - any chance this could be merged. this would really help with ipython... many thanks in any case for the great plugin!!

[001ben]

given iron.nvim has bracketed paste support - i've been using that for python repl in my latest setup

https://github.com/Vigemus/iron.nvim/blob/746414e67adcd3ad2ad5dbe6262543b55ac3f3cd/lua/iron/fts/common.lua#L97-L157

[mohelm]

Hey -

I will check it out thank you. Also for the PR here.

I found that this works:

map("n", "<localleader>m", function()
  set_opfunc(function(motion_type)
    --Hack to get bracked paste.
    tt.exec("\x1b[200~", 1)
    tt.send_lines_to_terminal(motion_type, false, { args = 1 })
    tt.exec("\x1b[201~", 1)
  end)
  vim.api.nvim_feedkeys("g@", "n", false)
end, { desc = "Send [M]otion to [T]erminal" })