" breakpts.vim " Author: Hari Krishna " Last Change: 05-Nov-2003 @ 19:19 " Created: 09-Jan-2003 " Requires: Vim-6.2, genutils.vim(1.10), multvals.vim(3.4) " Depends On: foldutil.vim (1.4) " Version: 3.0.5 " Acknowledgements: " - Thanks a lot to David Fishburn {fishburn at sybase dot com} for " providing a lot of feedback and ideas, and helping me with finding " problems. The plugin is much more usable and bug free because of him. " Licence: This program is free software; you can redistribute it and/or " modify it under the terms of the GNU General Public License. " See http://www.gnu.org/copyleft/gpl.txt " Download From: " http://www.vim.org/script.php?script_id=618 " Description: " - This plugin allows you to visually set/clear breakpoints in Vim " functions/scripts instead of using breakadd/breakdel commands. The " advantage is that you know exactly on which line you are setting the " breakpoint, especially when you use line-contnuation in your scripts. " Though setting breakpoints is the main intention, it is also useful as a " Vim function and script browser. " - Open the BreakPts window through WinManager (as described in the " installation section below) or by stand-alone using :BreakPts command " (or by pressing the hot key, if you have chosen one). You can use " :BreakPts (or the hot key) again to close the window. The :BreakPts " command also allows an option to be passed to specify the initial view " (+f for functions, +s for scripts, +b for breakpoints). " - The window is normally first opened with the list of all the functions " that are loaded into Vim. But you can toggle between the list of " functions, scripts and breakpoints, by using the :BPScripts, " :BPFunctions and :BPBrklist commands respectively, while in the BreakPts " window. " - Search for the function/script that you are interested in and press " or use :BPSelect command to get the listing. Alternatively you can use " :BPListFunc or :BPListScript command to list a function or script " directly. This is also the only way you can set a breakpoint in an " unloaded plugin (such as a ftplugin that is yet to be loaded). In the " script window, you can also use :BPOpen (or o) to open the script for " editing. " " TIP: You can use Vim's function or file name completion mechanism (if " enabled) with these commands. For script local functions, you can have " vim fill in the prefix (instead of manually typing it in), by " prefixing the function name an asterisk before attempting to complete. " - You can navigate the history by using and (or :BPBack and " :BPForward) commands, just like in an HTML browser. " - To toggle a breakpoint at any line, press (or :BPToggle) command. " The plugin uses Vim's |:sign| feature to visually indicate the existence " of a breakpoint. You can also use :BPClearAll command to clear all the " breakpoints. " - You can save the breakpoints into a global variable using the :BPSave " command while in the BreakPts window. The command takes in the name of a " global variable where the commands to recreate the breakpoints will be " saved. You can later reload these breakpoints by simply executing the " variable: " " :BPSave BL " :BPClearAll " . " . " :exec BL " " You can also use this technique to save and restore breakpoints across " sessions. For this, just make sure that the '!' option in 'viminfo' is " set: " " :set viminfo^=! " " and use a variable name that starts with an uppercase letter and contain " only uppercase letters and underscore characters (see help on " 'viminfo'). When you are no longer interested in saving and restoring a " breaklist, it is advisable to unlet the corresponding global variable. " - To make it easier to jump from one breakpoint to another, the plugin " defines two commands, [b and ]b (or :BPPrevious and :BPNext). Also, if " the foldutil.vim plugin is found to be installed, the plugin " automatically folds all the lines that do not have a breakpoint (with a " context of g:brkptsFoldContext, which has a default value of 3). This " feature is automatically disabled if foldutil.vim is not found to be " installed, but you can also set g:brkptsCreateFolds to 0 to explicitly " disable it. " - On the scripts view, you can use :BPReload (or O) to reload a script " after unletting the corresponding g:loaded_ variable. This " is intended to be used with the regular plugins, not the others such as " ftplugin, indent, syntax, colors or compiler plugins as these plugins " will automatically be reloaded by Vim at appropriate times. " " TIP: You can use this command to reload a new version of a plugin " without restarting your vim, but make sure the plugin supports such an " operation. Many plugins may not be designed to be just reloaded this way " as the script local variables could get reset causing it to misbehave. " - The contents of BreakPts window is cached, so to see the latest listing " at any time, refresh the window by pressing 'R' (or :BPRefresh) command. " You also need to refresh to see the breakpoints added/removed manually. " - To connect to a remote Vim using the |clientserver| functionality, open " the BreakPts window and use the :BPRemoteServ command with the Vim " server name as the argument (with no arguments the same command prints " the current remote server name). You can browse the functions/scripts " and set breakpoints in the remote session exactly as you would in the " local session. To get back to the local vim session, use the same " command with "." as the server name. " " Once the remote vim is in the debug mode (stopped at the > prompt), you " can use :BPDWhere command to view the context of the remote session. The " current line is marked with the BreakPtsContext highlighting group (by " default same as Visual). You can also execute the :debug mode commands " in the remote session as follows: " " Remote command Local command Local map " >next :BPDNext " >step :BPDStep " >cont :BPDCont " >quit :BPDQuit " >finish :BPDFinish " " - The plugin also provides two global functions BPBreak() and BPBreakIf() " which can be used to insert breakpoints dynamically. The BPBreak() " function works similar to the VB break command. It can also be used to " insert breakpoints from the debug prompt. The BPBreakIf() is just a " convenience function to conditionally break at a specified location. See " the function headers for more information. You need to patch 6.2 before " this feature can work. You can download the patch from: " " http://mywebpage.netscape.com/haridara/vim/breakpoint.patch.txt " " The patch also fixes a problem with the debug mode >cont command. " " Installation: " - Place the plugin in a plugin diretory under runtimepath and configure " WinManager according to your taste. E.g: " " let g:winManagerWindowLayout = 'FileExplorer,BreakPts' " " You can then switch between FileExplorer and BreakPts by pressing ^N " and ^P. " - If you don't want to use WinManager, you can still use the :BreakPts " comamnd or assign a hotkey by placing the following in your vimrc: " " nmap BreakPts " " You can substitute any key or sequnce of keys for in the above map. " - Requires multvals.vim to be installed. Download from: " http://www.vim.org/script.php?script_id=171 " - Requires genutils.vim to be installed. Download from: " http://www.vim.org/script.php?script_id=197 " - To have the g:brkptsCreateFolds feature enabled, install the " foldutil.vim plugin. Download from: " http://www.vim.org/script.php?script_id=158 " - Set g:brkptsSortFunctions if you want the functions to be sorted, but this " can slowdown the first appearance (and every refresh) of the BreakPts " window. To make the sort quicker, you can set the value of " g:brkptsSortExternalCmd to the name(e.g., "sort", if already in " PATH)/path of an external command. This will make the plugin use " external sort (which in general is much faster) instead of the built-in " sort. " - Set g:brkptsDefStartMode to 'script', 'function' or 'breaklist' to start " the browser in that mode. " - Set g:brkptsModFuncHeader to a true value, if you want to change " "function" to "function!" while listing functions. This will simplify you " to block copy the function and redefine it while still in debug mode " (kind of incremental update). " - Set the '!' flag in viminfo if you want to save the breaklist across " sessions (see usage above). " TODO: " Features: " - Implement BPDRunToCursor. Create a temporary checkpoint and clear it " when hit. " - It should be possible to run ctags to get all the local variables in the " current function and automatically show their values. We should also " be able to show the argument values automatically. " - It is possible for the debuggee scripts to provide a standard " interface (see perforce plugin for example) for the plugin to poke " into and obtain the script local values. " - How about a :BPDEvaluate command that takes in an expression and " evaluates it in the remote vim and shows the result (using " remote_expr() to be safe)? " - It should also be possible to create watch expressions to be evaluated " everytime the context is refreshed (using the :BPEvaluation infra.). " - How about opening an editable function listing window extracted from the " remote vim, and allow users to redefine it after modifying it? " - Need configurable shortcut keys. The current keys are modelled after " MS Visual Studio, but other IDEs use significantly different keys. " - I should be able to make better use of the stack produced by the " context. Maintain a local stack of current line numbers for them. But " I still will not be able to go up and down the stack, so may be not " that important. " - We need syntax rules for the BPScripts screen. " - A menu will be useful for those who are used to menus. " - We need a debug console to show the output of various debug commands. " " - How can I generate context without executing a normal command? " Using remote_expr() doesn't seem feasible. The same is applicable to " executing debug mode commands. " - Why is the column position getting reset in the listing window (only), " during the navigation? " - Why am I getting the remote output as this, sometimes: " 3 func...pl line 12 " 4 func...mpl line 1 " - Comments appear as strings. Need a new syntax rule. if exists('loaded_breakpts') finish endif if v:version < 602 echomsg "You need Vim 6.2 to run this version of breakpts.vim." finish endif if !exists("loaded_multvals") runtime plugin/multvals.vim endif if !exists("loaded_multvals") || loaded_multvals < 304 echomsg "breakpts: You need to have multvals version 3.4 or higher" finish endif if !exists("loaded_genutils") runtime plugin/genutils.vim endif if !exists("loaded_genutils") || loaded_genutils < 110 echomsg "breakpts: You need to have genutils version 1.10 or higher" finish endif let loaded_breakpts = 300 " Make sure line-continuations won't cause any problem. This will be restored " at the end let s:save_cpo = &cpo set cpo&vim " Initialization {{{ command! -nargs=? BreakPts :call BrowserMain(0, ) nnoremap