dotfiles / .vim / doc / Decho.txt

*decho.txt* Vim Code Debugger				Oct 23, 2008

Author:  Charles E. Campbell, Jr.  <drNchipO@ScampbellPfamilyA.bizM>
	  (remove NOSPAM from Campbell's email to use)
Copyright: (c) 2004-2008 by Charles E. Campbell, Jr.	*decho-copyright*
           The VIM LICENSE applies to Decho.vim and Decho.txt
           (see |copyright|) except use "Decho" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.

1. Contents						*decho-contents*

	1. Contents......................: |decho-contents|
	2. Decho Manual..................: |decho|
	3. Decho Global Variables........: |decho-var|
	4. Decho History.................: |decho-history|

	NOTE: as of version 7, Decho requires <cecutil.vim> for
	:DechoOn and :DechoOff (they call SaveWinPosn() and
	RestoreWinPosn() to retain the cursor/screen position)

2. Decho Manual						*decho* *dfunc* *dret*

	The Decho plugin supports the inlining of debugging code.  It allows
	one to store debugging information along with scripts.  Many of my]
	own scripts can use this plugin (usually after a :DechoOn is issued).

	Decho, Dfunc, Dret, and Dredir have several ways to save their
	debugging output: >

	 g:dechomode   To Enable   To Disable   Debugging Output
	 -----------   ----------  -----------  ---------------------------
	       1       (default)                appended to separate window
	       2       DechoMsgOn  DechoMsgOff  uses :echomsg
	       3       DechoVarOn  DechoVarOff  appended to g:dechovar
	       4       DechoRemOn  DechoRemOff  appended to a remote server
	       5       DechoTabOn  DechoTabOff  appended to a tab
	Why so many methods?  Although the default method, that of writing
	debugging output to a separate debugging window, is often quite
	convenient, sometimes plugins want to control the entire window
	display.  Hence a debugging window can cause trouble as it is
	unaccounted for by the plugin.  The :echomsg output can be seen with
	|:messages|, but only 20 such messages can be retained.  The remote
	server debugging output keeps its "distance" from plugins, but uses
	gvim to open a separate debugging instance.  So, pick whichever method
	suits debugging your plugin best.

	    call Decho("another string")
	    call Decho("yet","another","string")
	    call DechoSep(["extra message"])
	    call Dfunc("funcname(".whatever.")")
	    call Dredir(["string","string",...,]"cmd")
	    call Dret("funcname".whatever)
	    Decho "a string"
	    DechoOn    DechoOff
	    DechoVarOn [varname]
	    Dsep [extra-message]
	The Decho call will put the string(s) passed to it into the debugging
	window (by default, it will be called "DBG".  See |decho-var| for
	how to change that).  Control characters embedded in the string will
	be made visible with a ^A - ^Z transformation.

	The Dfunc() and Dret() calls act as a pair.  A function to be debugged
	should call, at entry, >

		call Dfunc("funcname("."any arguments".")")
	It should also call, just prior to any return point, >

		call Dret("funcname : any return values")
<	or just >
		call Dret("funcname")
	In between, calls to Decho will have their strings preceded by "|"s,
	one for every open Dfunc().  The Dret() will check to insure that it
	is apparently returning from the last function passed to Dfunc().

	Example: >
		function! MyFunction(x)
		  call Dfunc("MyFunction(x=".x.")")
		  call Dret("MyFunction")
       							*DechoOn* *DechoOff*
	DechoOn and DechoOff are convenient commands for enabling and disabling
	Decho, Dfunc, and Dret calls in a sourcefile.  DechoOff makes any line
	containing one of the following strings: >

    	    Decho        DechoRemOff  DechoTabOn   Dfunc
    	    DechoMsgOff  DechoRemOn   DechoVarOff  Dret
    	    DechoMsgOn   DechoTabOff  DechoVarOn

<	into a comment line and DechoOn reactivates such commands by removing
	the leading comment '"' character.

	Example: >
		call Decho("this will show up in the DBG buffer")
						*decho-dhide* *decho-dshow*
	The Dhide and Dshow commands allow one to toggle the visibility of
	the DBG-buffer.  They use the g:decho_hide variable, plus make any
	current DBG-buffer hidden or visible as indicated.

	Usage: >
							*Dsep* *DechoSep*
	This command (Dsep) and function (call DechoSep([optional msg])
	places a line of the form >
		--sep#-- [optional message here]
<	in the debugging output.  The number will be incremented for each
	time this function is invoked.  It helps one correlate an action
	with the resulting debugging output.

							*decho-redir* *Dredir*
	The Dredir() function allows one to redirect (see |redir|) a command's
	output to the debugging buffer.  One must have the command to be
	executed as the first argument; optionally, one may include additional
	arguments which will be passed on to Decho() for output.

	Usage: >
		call Dredir(["string","string",...,]"cmd")
	Example: >
		call Dredir("buffers","ls!")
	Some plugins use events such as BufEnter, WinEnter, and WinLeave.  If
	you set this variable to 1, then such events will be ignored when and
	only when Decho() and variants are used.  Setting this option avoids
	such plugins from being triggered when recording debugging messages.
	(examples: winmanager, taglist, multiselect, etc)

	Example: >
		let g:decho_bufenter= 1
						*DechoVarOn* *DechoVarOff*
	Although debugging to a window is often convenient for the programmer,
	unfortunately some vim applications are incompatible with such a
	window (such as those which do window control themselves).  Using >
<	sends debugging output to be appended to a variable named in the
	|g:dechovarname| variable (by default, its "g:dechovar").  To turn
	this mode off (ie. revert to normal debugging-window use) use >
<	DechoVarOn also sets g:dechofile with the name of the script that
	invoked it.
						*DechoMsgOn* *DechoMsgOff*
	This debugging method uses echomsg to display messages; they may be
	seen with the |:messages|.  Vim usually will retain up to 20 such
	messages (see |message-history|).  Use >
<	to turn this method on and >
<	to revert to normal debugging-window use.  This method helps avoid
	interference with some plugins.
	DechoMsgOn also sets g:dechofile with the name of the script that
	invoked it.

						*DechoRemOn* *DechoRemOff*
	This method will open (if necessary) and use a remote gvim with a
	servername of DECHOREMOTE.  Debugging messages are appended to that
	instance of gvim.  To have this command available, your vim must have
	|clientserver| enabled and |gvim| must be executable. Use >
<	to turn this method on and >
<	to revert to normal debugging-window use.  This method helps avoid
	interference with some plugins.

	DechoRemOn also sets g:dechofile with the name of the script that
	invoked it.

						*DechoTabOn* *DechoTabOff*
	This method will open (if necessary) and use a debugging tab with
	one window.  Debugging messages are appended to the debugging tab
	(see |tabpage|).  One may use |gt| to switch between two tabs.  Use >
<	to turn this method on and >
<	to revert to normal debugging-window use.  The Decho and related
	calls turn events off while writing to the debugging tab so as to
	attempt to remain transparent with respect to normal event processing.


	Consider the following file: >
	    let x="abc"
	    let y="def"
	    call Dfunc("testing(x=".x.")")
	    call Decho("decho test #1")
	    call Dfunc("Testing(y=".y.")")
	    call Decho("decho test #2")
	    call Dret("Testing")
	    call Decho("decho test #3")
	    call Dret("testing")
	Then sourcing with <Decho.vim> as a plugin (ie. already loaded) yields: >

	    testing(x=abc) {
	    |decho test #1
	    |Testing(y=def) {
	    ||decho test #2
	    ||Testing }
	    |decho test #3
	    |testing }
	DechoRemOn also sets g:dechofile with the name of the script that
	invoked it.

3. Decho Global Variables		*decho-variables* *decho_settings*
					*decho_options* *decho-var*

   *g:dechomode*      :	=1 use separate small window at bottom (default)
			=2 debugging messages will use echomsg and can be seen
			   by using :messages.  See |message-history| for more
			   about this; currently, the maximum number of mess-
			   ages remembered is 20.
			=3 debugging messages get appended to the variable
			   named by |g:dechovarname| (also see |g:dechovar|)
			=4 debugging messages get appended to the gvim remote
			   server named DECHOREMOTE.

   *g:decho_bufname*  :	by default "DBG" .  Sets the name of the debugging
   			buffer and window.
   *g:decho_hide*     :	if set the DBG window will be hidden and will
   			automatically "q" each time it is used.  To see it,
			:e DBG .  Useful for those applications that
			modify windows.
   *g:dechovar*       : default value of g:dechovarname (see |g:dechovarname|)

   *g:dechovarname*   : when g:dechomode is 3, debugging output is appended to
			the variable named by this variable
			(default: "g:dechovar"  - see |g:dechovar|)

   *g:decho_winheight* : by default equal to 5 lines.  Specifies the height
			 of the debugging window.  Every Dfunc/Decho/Dret
			 call will resize that window to this height.

4. Decho History					*decho-history*

  v20 Jun 07, 2007 : * changed some syntax/Decho.vim highlighting definitions
		       to avoid the use of highlighting groups defined by
		       colors/astronaut.vim that aren't standard (Cyan,
		       Magenta) (pointed out by Andreas Politz)
		     * (Erik Falor) under windows, uses "start gvim..."so
		       that DechoRemOn doesn't keep the original gvim
		       blocking until the remote gvim closes.
		     * (Erik Falor) The remote gvim now has |'nosi'| sent to it.
      Feb 13, 2008   * changed s:DechoSep() to DechoSep() so that it can be
		       called externally.  In particular, I'm using (all one
		       line): >
		         redraw!|call DechoSep()|...
		         call inputsave()|call input("Press <cr> to continue")|...
		         call inputrestore()
<		       to put a temporary halt into code I'm debugging while
		       retaining an idea of where in the Debug file it took
      May 29, 2008   * Removed an annoying beep that could crop up if
                       g:dechotabnr indexed a non-existent tab page.
      Aug 12, 2008   * DechoRemOn left autoindent enabled in the remote
		       window which can cause staircasing
      Oct 13, 2008   * in DechoTab mode, the search for the first tab called
		       "Decho Tab" didn't start at tab#1 as the search loop
  v19 Oct 16, 2006 : * Dredir now takes optional strings first instead of
		     * The :Decho and :Dredir commands now take <args> instead
		       of <q-args>, which allows them to act more like the
		       function calls do.
		     * DechoRemOn's remote vim no longer will have
		       formatoptions' a or t suboptions set even if the user
		       has specified something like fo+=at in his/her .vimrc.
		     * If the user interposes a new tab (or deletes the
		       "Decho Tab"), Decho finds the "Decho Tab" tab or
		       creates a new one when called.
  v18 Mar 13, 2006 : * now handles arguments which are lists
                     * works around ignorecase setting
		     * removed bt=nofile; using noswf instead
      Sep 08, 2006   * if DechoRemOn is used, but then the user closes the
                       remote window but still sends Decho messages, then
		       Decho now switches to DECHOWIN mode to prevent an
		       onslaught of error messages about how vim can't connect
		       to the DECHOREMOTE vim.
  v17 Mar 03, 2006 : * debugging filetype set to Decho for DechoTabOn and
                       DechoRemOn and ei manipulated so that syntax
		       highlighting works for the Decho Tab buffer.
		     * bugfix: when a buffer was |'noma'|, DechoTabOn
		       inherited that and complained about not being allowed
		       to modify the buffer.
  v16 Feb 27, 2006 : * reflecting changes to tab commands:
                       tab -> tabn, tabn -> tabnew
  v15 Feb 21, 2006 : * DechoTab[On\Off] implemented
  v14 Jan 25, 2006 : * bugfix: with DechoVarOn, Decho would issue error
                       messages when the string had single quotes (') in
		     * SaveWinPosn(0) used to avoid SWP stack use
      Feb 15, 2006   * DechoRemOn and DechoRemOff now turn debugging on/off to
		       a remote DECHOREMOTE gvim server.  Your vim must
		       support clientserver and gvim must be executable.
  v13 Jan 18, 2006 : * cecutil updated to use keepjumps
  v12 Jan 14, 2005 : * DechoOn/Off now also turns on/off DechoVarOn/Off
                     * Now includes a GetLatestVimScripts line for cecutil.vim
      Apr 25, 2005   * Decho now does "runtime plugin/cecutil.vim" if that plugin
                       hasn't been loaded yet.  It will also try the AsNeeded
		       subdirectory if g:loaded_asneeded exists.
      Jun 02, 2005   * with DechoMsgOn, Decho("doesn't") now works
  v11 Aug 06, 2004 : * <q-args> now used instead of <args> for :Decho and :Dredir
      Oct 28, 2004   * DechoMsgOn and DechoMsgOff installed; debugging messages
                       will use the |echomsg| command.
      Dec 27, 2004   * DechoVarOn and DechoVarOff installed; debugging
      		       messages will be appended to the variable specified by
		       g:dechovarname, which by default is "g:dechovar".
		       These two commands toggle the variable
      Dec 29, 2004   * Dredir() now accepts multiple arguments (cmd and output)
  v10 Jul 27, 2004 : * if g:decho_bufenter exists, Decho will ignore BufEnter
		     * Decho uses keepjumps to avoid altering the jumplist
		     * appending to the DBG buffer with Decho does not make
		       it modified
		     * Dredir(cmd) may be used to redirect command output
		       to the DBG buffer.  Example:  call Dredir("cmd")
   v9 Jun 18, 2004 : * Dfunc/Decho/Dret now immune to lcd changes in the DBG
   		       buffer name
                     * DechoOn and DechoOff now accept ranges
   v8 Jun 06, 2004 : * Implemented Dhide and Dshow commands for toggling
                       the DBG-buffer's visibility (see |decho_dhide|)
   v7 Jun 02, 2004 : * made creation of	DBG window silent
		     * g:decho_winheight implemented (see |decho_winheight|)
		     * Dfunc/Decho/Dret	will always resize the DBG window to the
		       number of lines specified by g:decho_winheight (dflt:5)
		     * g:decho_hide implemented (see |decho_hide|)
   v6 May 11, 2004 : * some bug	fixes
   v5 Apr 20, 2004 : * Dfunc() - for entering a	function
		     * Dret()  - for returning from a function
   v4 Apr 20, 2004 :   Now makes control characters visible
   v3 Aug 07, 2003 : * changed fixed "DBG" to g:decho_bufname to allow s/w to
		       change the buffer name!
		     * Now handles returning cursor to one of several windows
		       and having multiple DBG-windows