*CCTree.txt*	Plugin for C Call-Tree Explorer *CCTree*

Author: Hari Rangarajan (First.Last AT gmail DOT com)
Last Change: 20 May 2011

CCTree version 1.51

For Vim version 7.0 and above

==============================================================================

1. Overview                                     |CCTree-overview|
2. Downloads                                    |CCTree-download|
3. Installation                                 |CCTree-installation|
4. Configuration				|CCTree-configuration|
5. Features                                     |CCTree-features|
6. Limitations                                  |CCTree-limitations|
7. FAQ & TIPS                                   |CCTree-faq|
8. History                                      |CCTree-history|
9. Thanks                                       |CCTree-thanks|
 
==============================================================================
1. Overview~
                                                *CCTree-overview*

Plugin generates dependency-trees for symbols using a cscope database in Vim.
Basic cross-referencing includes functions and macros. Enhanced symbol
processing covers macros, typedefs, enums, and global variables.

Requires Cscope and works best with C code.

==============================================================================
2. Downloads~
                                                *CCTree-download*

You can download the latest release of the script from this url :
    http://www.vim.org/scripts/script.php?script_id=2368


Cscope packages can be found here:
    http://cscope.sourceforge.net/
    http://code.google.com/p/cscope-win32/
    

==============================================================================
3. Installation~
                                                *CCTree-installation*

Copy this file to ~/.vim/plugins/ or to /vimfiles/plugins/  (on Win32
platforms) 

It should also be possible to load it as a filetype plugin ~/.vim/ftplugin/c/
Need to set :filetype plugin on 


==============================================================================
CONFIGURATION					*CCTree-configuration*
4. Options~

You can customize behavior by changing the following variable settings
                    
4.1.1 Cscope Symbol Database~
                                                *CCTreeCscopeDb*

Cscope database file, g:CCTreeCscopeDb = "cscope.out"

4.1.2 Call-tree Depth~
                                                *CCTreeRecursiveDepth* 
Maximum call levels,   g:CCTreeRecursiveDepth = 3

4.1.3 Call-tree Minimum Visible Depth~
                                                *CCTreeMinVisibleDepth*
Maximum visible(unfolded) level, g:CCTreeMinVisibleDepth = 3

4.1.4 Call-tree window display~

4.4.1 Orientation~
                                                *CCTreeOrientation*
Orientation of window,  g:CCTreeOrientation = "leftabove"
 (standard vim options for split: [right|left][above|below])

4.5 Direction~
                                                *CCTreeWindowVertical* 
Use Vertical window, g:CCTreeWindowVertical = 1

4.5.1 Dimensions~

These settings determine the layout of the CCTree preview window.

4.5.2 Horizontal Window Settings~
                                                *CCTreeWindowHeight* 
 Horizontal window, g:CCTreeWindowHeight, default is -1.

4.5.2 Vertical Window Settings~
                                                *CCTreeWindowMinWidth* 
                                                *CCTreeWindowWidth* 
 Minimum width for window, g:CCTreeWindowMinWidth = 40.
 g:CCTreeWindowWidth = -1, auto-select best width to fit.


4.6 Call-tree display format~
                                                *CCTreeDisplayMode*
Display format, g:CCTreeDisplayMode, default: 1

Values: 1 -- Ultra-compact (takes minimum screen width)
        2 -- Compact       (Takes little more space)
        3 -- Wide          (Takes copious amounts of space)

For vertical splits, 1 and 2 are good, while 3 is good for horizontal
displays.

4.7. Dynamic Call-tree highlighting~
                                                *CCTreeHilightCallTree*

Enable/disable dynamic call-tree highlighting, default: 1


4.7.1 Syntax items~
                                               *CCTreeSymbol* *CCTreeHiSymbol*
CCTreeSymbol is the symbol name.
CCTreeHiSymbol is the highlighted call tree functions.

                                               *CCTreeMarkers* *CCTreeHiMarkers*
CCTreeMarkers include  "|","+--->".
CCTreeHiMarkers is the same as CCTreeMarkers except these denote the 
highlighted call-tree.

    
   
==============================================================================
COMMAND LIST 						*CCTree-commands-list*

Database Management~
      CCTreeLoadDB                <dbname>
      CCTreeAppendDB              <dbname>
      CCTreeUnLoadDB             
      CCTreeShowLoadedDBs
				Refer to |CCTree-usage|

Native Xref Database~
      CCTreeLoadXRefDB		 <dbname>
      CCTreeSaveXRefDB		 <dbname>
				
				Refer to |CCTree-fast-loading|
	
Symbol tracing~
      CCTreeTraceForward          <symbolname>
      CCTreeTraceReverse          <symbolname>     
      CCTreeRecurseDepthPlus     
      CCTreeRecurseDepthMinus    
				Refer to |CCTree-explore-source|
Trace Management~
      CCTreeWindowSaveCopy
      CCTreeWindowHiCallTree   
				Refer to |CCTree-preview-window|

Dynamic configuration~
      CCTreeOptsEnable <option>    (<tab> for auto-complete)
      CCTreeOptsDisable <option>   (<tab> for auto-complete)
      CCTreeOptsToggle <option>    (<tab> for auto-complete)
      Options~
            DynamicTreeHiLights: Control dynamic tree highlighting
	    UseUnicodeSymbols: 	 Use of UTF-8 special characters for tree
            UseConceal: Use (+Conceal) feature instead of 'ignore'
                    syntax highlighting. Allows CCTree window
                    to be exported in HTML without syntax markup
                    characters. (Vim 7.3+ only)
                                            *CCTree-Enhanced-Symbol-Processing*
            EnhancedSymbolProcessing: Cross-reference enums, macros,
                    global variables, typedefs (WARNING: Database
                    processing speeds will be slow).
 
SHORTCUT KEYS						*CCTree-Key-Map*	
Default Mappings~
							*CCTree-Default-Key-Map*   
      Get reverse call tree for symbol  <C-\><
      Get forward call tree for symbol  <C-\>>
      Increase depth of tree and update <C-\>=
      Decrease depth of tree and update <C-\>-

      Open symbol in other window       <CR>
      Preview symbol in other window    <Ctrl-P>

      Save copy of preview window       <C-\>y
      Highlight current call-tree flow  <C-l>
      Compress(Fold) call tree view     zs
      (This is useful for viewing long
       call trees which span across
       multiple pages)

Custom user-mappings	
							*CCTree-Custom-Key-Map*
    Users can custom-map the short-cut keys by 
    overriding the following variables in their
    Vim start-up configuration            
>
     let g:CCTreeKeyTraceForwardTree = '<C-\>>' 
     let g:CCTreeKeyTraceReverseTree = '<C-\><' 
     let g:CCTreeKeyHilightTree = '<C-l>'        " Static highlighting
     let g:CCTreeKeySaveWindow = '<C-\>y' 
     let g:CCTreeKeyToggleWindow = '<C-\>w' 
     let g:CCTreeKeyCompressTree = 'zs'     " Compress call-tree 
     let g:CCTreeKeyDepthPlus = '<C-\>=' 
     let g:CCTreeKeyDepthMinus = '<C-\>-'
<  

==============================================================================
FEATURES 						*CCTree-features*

5.1. Symbol database~
							*CCTree-usage*
Build cscope database, for example:
> cscope -b -i cscope.files
 [Tip: add -c option to build uncompressed databases for faster
    load speeds]

Load database~
>
	:CCTreeLoadDB
<
	(Please note that it might take a while depending on the 
	 database size)

A database name, i.e., my_cscope.out, can be specified with the command. If
not provided, a prompt will ask for the filename; default is cscope.out.
	
Unload database ~
 >
 	:CCTreeUnLoadDB
<
Append database~
 >
	:CCTreeAppendDB
<
    Allows multiple cscope files to be loaded and cross-referenced
    Illustration: >
    :CCTreeAppendDB ./cscope.out
    :CCTreeAppendDB ./dir1/cscope.out
    :CCTreeAppendDB ./dir2/cscope.out
<
    A database name, i.e., my_cscope.out, can be specified with 
    the command. If not provided, a prompt will ask for the 
    filename; default is cscope.out.

FASTER DATABASE LOADING					*CCTree-fast-loading*

Save native Xref Db~
>
	:CCTreeSaveXRefDb  cctree.out
<
This command will save the cross-referenced symbols currently loaded into 
memory into a serialized format  for faster loading.

Load native XRef Db~
>
	:CCTreeLoadXRefDb  cctree.out
<
This command will load cross-referenced symbols from the previously saved
native format database.

ccglue~
                                                       *CCTree-ccglue*

Check out the ccglue project at http://ccglue.sourceforge.net for an external
tool that can build cctree-compatible xref databases.


5.2. Exploring source-code~
							*CCTree-explore-source*

Get reverse call tree for symbol  <C-\><
>
	:CCTreeTraceReverse <symbolname>     
<

Get forward call tree for symbol  <C-\>>
>
	:CCTreeTraceForward <symbolname>
<
Increase depth of tree and update <C-\>=
>
	:CCTreeRecurseDepthPlus     
<
Decrease depth of tree and update <C-\>-
>
	:CCTreeRecurseDepthMinus    
<
5.3. Preview Window~
						 *CCTree-preview-window*
Open symbol in other window       <CR>
Preview symbol in other window    <Ctrl-P>

5.4. Syntax Coloring~
						 *CCTree-Syntax*
CCTreeHiXXXX allows dynamic highlighting of the call-tree.  To observe the
effect, move the cursor to the function to highlight the current call-tree.
This option can be turned off using the setting, *CCTreeHilightCallTree* . 

For faster highlighting, the value of 'updatetime' can be changed.

5.5 Support for large database files~
				*CCTree-LargeDatabase* *CCTree-LargeFile*
Vimscript does not have an API for reading files line-by-line. This
becomes a problem when parsing large databases. CCTree can overcome
the limitation using an external utility (i.e., GNU coreutils: split)
or VimScript's perl interpreter interface (:version must indicate +perl)

5.5.1 Using GNU Coreutils (split/cat)~
				*CCTree-Tools-split* *CCTree-Tools-cat*
	The following settings are tailored to suit GNU coreutils split; the
default settings should work with no changes on typical linux/unix distros.
Monopoly OSes will require installation of unixutils or equivalent.

External command is setup with the following parameters~
>
	let g:CCTreeSplitProgCmd = 
		'PROG_SPLIT SPLIT_OPT SPLIT_SIZE IN_FILE OUT_FILE_PREFIX'
<

Break-down of individual parameters~
The split utility is assumed to be on the path; otherwise, specify full path
	g:CCTreeSplitProg = 'split'

Option for splitting files (-C or -l)~
>
	let g:CCTreeSplitProgOption = '-C'
<
If split program does not support -C, then this parameter must be set to 
the number of lines in the split files
>
	let g:CCTreeDbFileSplitLines = -1
<
Largest filesize Vimscript can handle; file sizes greater than this will
be temporarily split
>
	let g:CCTreeDbFileMaxSize  = 40000000 (40 Mbytes)
<
Sample system command~
Typical:
>
	split -C 40000000 inputFile outputFilePrefix
<
 When g:CCTreeDbFileSplitLines is set to 10000 (-C options will be ignored)
>
	split -l 10000 inputFile outputFilePrefix
<
						*CCTree-Tools-Perl*
						*CCTree-Tools-Perl-LargeFile*
Enabling perl interface~

	By default, perl usage is disabled. Set
>
	let g:CCTreeUsePerl = 1 
<		 to enable the perl interface.

	Perl interface is typically faster than native Vimscript.
	This option can be used independent of the file size

	For more info on setting up perl interface
	:help |perl-using| or :help |perl-dynamic|

5.6.	Miscellaneous				*CCTree-Miscellaneous*

	UTF-8 usage				*CCTree-UTF8-Symbols*
            UTF-8 symbols should work fine on the majority of
        X11 systems; however, some terminals might cause problems.

        To use symbols for drawing the tree, this option can be enabled.
>
            let g:CCTreeUseUTF8Symbols = 1 
<
        The options interface (CCTreeOptsxxx) can be used to 
        modify options on-the-fly.

==============================================================================
6. Limitations~
                                                *CCTree-limitations*

The following are known limitations:

Basic Symbol Processing:
  (1) The accuracy of the call-tree will only be as good as the cscope database
generation.  (NOTE: Different flavors of Cscope have some known limitations
due to the lexical analysis engine. This results in incorrectly identified
function blocks, etc.)

Enhanced Symbol Processing:
  (1) Cscope does not mark-up nameless enums correctly; hence,
CCTree cannot recognize nameless enum symbols.


==============================================================================
7. FAQ~
                                                *CCTree-faq*

+ I see strange characters "!#@" on my screen when dynamic highlighting is
enabled. Why do I see them?
  
Check :hi ignore. You will see something like
hi ignore ctermfg=white guifg=bg
    
  For console, white must be your background color; for GUI, guifg must be set
to bg.

==============================================================================
8. History~
                                                *CCTree-history*
Version 1.51: May 18, 2011
      1. Robust error reporting when external (split/cat) utils fail

Version 1.50: May 6, 2011
      1. Support cross-referencing of global variables, macros,
         enums, and typedefs.

Version 1.40: April 22, 2011
      1. Maintain order of functions called during forward tracing

Version 1.39: April 18, 2011
      1. Use +Conceal feature for highlighting (only Vim 7.3)

Version 1.33: April 5, 2011
      1. Load and trace CCTree native XRefDb directly from disk
      2. Fix AppendDB command when 'ignorecase' is set

Version 1.26: March 28, 2011
      1. Fix macro cross-referencing limitation
      2. Correct native xref file format

Version 1.21: March 21, 2011
      1. Support serialization of loaded
                cscope databases (for faster loading)

Version 1.07: March 09, 2011
      1. Fix new keymaps incorrectly applied to buffer
      2. CCTreeOptsToggle command for toggling options

Version 1.04: March 06, 2011
      1. Customization for key mappings
      2. Dynamic configuration of UI variables
      3. Folding long call-trees to show current path dynamically

Version 1.01: March 04, 2011
      1. Make UTF-8 symbols for tree optional

Version 1.00: March 02, 2011
      1. Staging release for upcoming features
         - Complete refactoring of code to take 
                advantage of VimScript's OO features
      2. Faster decompression of symbols
      3. Display related changes
         - Use of unicode symbols for tree
      4. Bugfixes related to multi-database loading
               
Version 0.90: February 18, 2011
      1. Support for large databases using external split utility or perl
         interface

Version 0.85: February 9, 2011
      1. Significant increase in database loading and decompression speeds

Version 0.80: February 4, 2011
      1. Reduce memory usage by removing unused xref symbols

Version 0.75: June 23, 2010
	  1. Support for saving CCTree preview window; multiple 
    	CCTree windows can now be open

ersion 0.71: May 11, 2010
	  1. Fix script bug

Version 0.70: May 8, 2010
	  1. Functionality to load multiple cscope databases

Version 0.65: July 12, 2009
	  1. Toggle preview window

Version 0.61: December 24, 2008
      1. Fixed bug when processing include files
      2. Remove 'set ruler' option

Version 0.60: November 26, 2008
      1. Added support for source-file dependency tree

Version 0.50: October 17, 2008
      1. Optimizations for compact memory foot-print and 
         improved compressed-database load speeds

Version 0.41: October 6, 2008
       1. Minor fix: Compressed cscope databases will load
       incorrectly if encoding is not 8-bit

Version 0.4: September 28, 2008
      1. Rewrite of display-related code
      2. New syntax hightlighting
      3. Dynamic highlighting for call-trees
      4. Support for new window modes (vertical, horizontal)  
      5. New display format option for compact or wide call-trees
      6. Preview window fix

Version 0.3: September 21, 2008
      1. Support compressed cscope databases
      2. Display window related bugs fixed
      3. More intuitive display and folding capabilities
    
Version 0.2: September 12, 2008
      (Patches from Yegappan Lakshmanan, thanks!)
      1. Support for using the plugin in Vi-compatible mode
      2. Filtering out unwanted lines before processing the db
      3. Command-line completion for the commands
      4. Using the cscope db from any directory

Version 0.1: August 31,2008
      1. Cross-referencing support for only functions and macros
         (Note: Functions inside macro definitions will be incorrectly
         attributed to the top level calling function)


==============================================================================
9. Thanks~
                                                 *CCTree-thanks*


   Qaiser Durrani                 (ver 1.51 -- Reporting issues with SunOS)
   Ben Fritz                      (ver 1.39 -- Suggestion/Testing for 
                                                        conceal feature)
   Ben Fritz                      (ver 1.26 -- Bug report)
   Frank Chang                    (ver 1.0x -- testing/UI enhancement 
                                                            ideas/bug fixes)
   Arun Chaganty/Timo Tiefel	  (Ver 0.60 -- bug report)
   Michael Wookey                 (Ver 0.40 -- Testing/bug report/patches)
   Yegappan Lakshmanan            (Ver 0.20 -- Patches)

   The Vim Community, ofcourse :)


vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: