" breakpts.vim " Author: Hari Krishna " Last Change: 06-May-2004 @ 20:08 " Created: 09-Jan-2003 " Requires: Vim-6.3, genutils.vim(1.13), multvals.vim(3.6) " Depends On: foldutil.vim(1.4), cmdalias.vim(1.0) " Version: 3.2.1 " Acknowledgements: " - Thanks a lot to David Fishburn (fishburn at sybase dot com) for " providing a lot of feedback, ideas and patches, and helping me with " finding problems. The plugin is much more usable and bug free because of " him. " - Bram and Michael Geddes (mgeddes at au dot mediacommand dot com) for " fixing the Vim crashes with remote debugging. " 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). As a " convenience, you can also convert any number of existing buffers to " additional BreakPts buffers by executing the :BreakPtsSetupBuf command. " This allows you to display as many windows as you want each with " different lists/listings. " " E.g., you can convert an arbitrary buffer to display the :breaklist (by " executing the :BPPoints command) and use it to enable/disable " 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 :BPPoints 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 a script script " that is already loaded for editing. BPListScript command can take an " absoluate path or a relative path that is valid from the current " directory or any directory in the 'runtimepath' as an argument. " " 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 with 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 when you are in the BreakPts window (or :BreakPtsClearAll " in other windows). " - You can save the breakpoints into a global variable using the :BPSave " command while in the BreakPts window (or using the :BreakPtsSave in " other windows). 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 to work, 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 " locally or remotely. This basically determines the corresponding " g:loaded_ variable by following some simple rules and " sources this script after unletting the 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 (all my other plugins do, as this is what I do during the " development process). 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. " CAUTION: This commands results in a loss of forward history. " - 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 defines a global command called :Where which you can use " during the debugging to see the context of the current line. " - Creates the following commands with useful completions, and alias them " to the corresponding built-in commands if cmdalias.vim is loaded. " - :Runtime (for |:runtime|) that allows you to do partial file " completions from your 'runtimepath'. " - :Debug (for |:debug|) that allows you to do command-completions. " - :Breakadd (for |:breakadd|) that allows you to complete on the " function name or file path (from 'runtimepath'). " - :Breakdel (for |:breakdel|) that allows you to complete on the " existing breakpoints (obtained from :breaklist). " - The plugin also provides two global functions BPBreak() and BPBreakIf() " which can be used to insert, and two more global functions BPDeBreak() " and BPDeBreakIf() for clearing 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. " " 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 'scripts', 'functions' or 'breakpts' 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). " - The default maps for debug commands are defined based on the MS Visual " Studio, but you can easily configure them. " " Here is a table of all the mappings and their default key associations: " " Mapping Default Description~ " BreakPtsContKey Continue execution (>cont). " BreakPtsQuitKey Quit debug mode (>quit). " BreakPtsNextKey Exeute next command (>next). " BreakPtsStepKey Step into next command (>step). " BreakPtsFinishKey Finish executing current " function/script (>finish). " BreakPtsClearAllKey Clear all breakpoints. " " E.g., to change the mapping for the BreakPtsContKey to , place the " following in your vimrc: " " nmap