Name Of File: *cctree.txt*
 Description: C Call-Tree Explorer Vim Plugin
  Maintainer: Hari Rangarajan <hari.rangarajan@gmail.com>
         URL: http://vim.sourceforge.net/scripts/script.php?script_id=2368
 Last Change: June 10, 2012
     Version: 1.61

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

 {{{ Description:
      Plugin generates dependency-trees for symbols using a cscope database
 in Vim.
 }}}
 {{{ Requirements: 1) Vim 7.xx , 2) Cscope

               Tested on Unix and the following Win32 versions:
               + Cscope, mlcscope (WIN32)
                      http://code.google.com/p/cscope-win32/
                      http://www.bell-labs.com/project/wwexptools/packages.html
 }}}
 {{{ Installation:
              Copy this file to ~/.vim/plugins/
              or to /vimfiles/plugins/  (on Win32 platforms)

              It might also be possible to load it as a filetype plugin
              ~/.vim/ftplugin/c/

              Need to set :filetype plugin on

 }}}
 {{{ 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 with command ":CCTreeLoadDB"
          (Please note that it might take a while depending on the
          database size)

          Append database with command ":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.

          To show loaded databases, use command ":CCTreeShowLoadedDBs"

          To unload all databases, use command ":CCTreeUnLoadDB"
           Note: There is no provision to unload databases individually

          To save the current set of databases loaded in to memory onto disk
          in native CCTree XRef format, use command ":CCTreeSaveXRefDB"

          To load a saved native CCTree XRef format file, use
          command ":CCTreeLoadXRefDB"

          To load a saved native CCTree XRef format file, use
          command ":CCTreeLoadXRefDBFromDisk"

          Notes: No merging database support for CCTree native DB's [at present].


           To have multiple CCTree preview windows, use ":CCTreeWindowSaveCopy"
           Note: Once saved, only the depth of the preview window can be changed

          Default Mappings:
            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:
          Users can custom-map the short-cut keys by
          overriding the following variables in their
          Vim start-up configuration

           g:CCTreeKeyTraceForwardTree = '<C-\>>'
           g:CCTreeKeyTraceReverseTree = '<C-\><'
           g:CCTreeKeyHilightTree = '<C-l>'        " Static highlighting
           g:CCTreeKeySaveWindow = '<C-\>y'
           g:CCTreeKeyToggleWindow = '<C-\>w'
           g:CCTreeKeyCompressTree = 'zs'     " Compress call-tree
           g:CCTreeKeyDepthPlus = '<C-\>='
           g:CCTreeKeyDepthMinus = '<C-\>-'

         Command List:
            CCTreeLoadDB                <dbname>
            CCTreeAppendDB              <dbname>
            CCTreeLoadXRefDB            <dbname>
            CCTreeSaveXRefDB            <dbname>
            CCTreeLoadXRefDBFromDisk    <dbname>

            CCTreeUnLoadDB
            CCTreeShowLoadedDBs

            CCTreeTraceForward          <symbolname>
            CCTreeTraceReverse          <symbolname>
            CCTreeRecurseDepthPlus
            CCTreeRecurseDepthMinus
            CCTreeWindowSaveCopy

         Only in preview window:
            CCTreeWindowHiCallTree   (same as <C-l> shorcut)
                  Highlight calling tree for keyword at cursor

         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)
                  EnhancedSymbolProcessing: Cross-reference enums, macros,
                              global variables, typedefs (Warning: Database
                              processing speeds will be slow).



         Settings:
              Customize behavior by changing the variable settings

              UTF-8 usage:
                  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.
                  g:CCTreeUseUTF8Symbols = 1
              The options interface (CCTreeOptsxxx) can be used to
              modify options on-the-fly.

              Cscope database file, g:CCTreeCscopeDb = "cscope.out"
              Maximum call levels,   g:CCTreeRecursiveDepth = 3
              Maximum visible(unfolded) level, g:CCTreeMinVisibleDepth = 3
              Orientation of window,  g:CCTreeOrientation = "topleft"
               (standard vim options for split: [right|left][above|below])

              Use Vertical window, g:CCTreeWindowVertical = 1
                  Min width for window, g:CCTreeWindowMinWidth = 40
                  g:CCTreeWindowWidth = -1, auto-select best width to fit

              Horizontal window, g:CCTreeWindowHeight, default is -1


              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

              NOTE: To get older behavior, add the following to your vimrc
              let g:CCTreeDisplayMode = 3
              let g:CCTreeWindowVertical = 0

              Syntax Coloring:
                   CCTreeSymbol is the symbol name
                   CCTreeMarkers include  "|","+--->"

                   CCTreeHiSymbol is the highlighted call tree functions
                   CCTreeHiMarkers is the same as CCTreeMarkers except
                          these denote the highlighted call-tree


                   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, g:CCTreeHilightCallTree.
                   For faster highlighting, the value of 'updatetime' can be
                   changed.

              Support for large database files:
                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)

               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:
               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)
                           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
                        g:CCTreeDbFileSplitLines = -1
               Largest filesize Vimscript can handle; file sizes greater than this will
               be temporarily split
                       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


               Using perl interface:
                       By default, perl usage is disabled. Set
                       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

              Writing large Xref Databases:
                  CCTree can use external utilities to write extremely large files beyond
              VimScripts capabilities. It requires the use of an external tool that can
              join text files (i.e., 'cat' in unix). This utility is triggered if the size
              of the file being written exceeds g:CCTreeDbFileMaxSize (40 Mb or as configured)

              The join utility command is configured by default as follows:
              let CCTreeJoinProgCmd = 'PROG_JOIN JOIN_OPT IN_FILES > OUT_FILE'

              let  g:CCTreeJoinProg = 'cat'           " PROG_JOIN
              let  g:CCTreeJoinProgOpts = ""          " JOIN_OPT


 }}}
 {{{ Limitations:
          Basic Symbol Processing:
              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.
 }}}
 {{{ History:
          Version 1.61: June 10, 2012
                1. Compability patch for change in tag file format starting
                from ccglue version 0.6.0
          Version 1.60: July 14, 2011
                1. Speed-up call-tree depth manipulation using incremental
                updates
          Version 1.55: June 20, 2011
                1. Speed-up syntax highlighting by restricting to visible
                area (Note: To export to HTML, run TOhtml command on cctree window 
                copy to get complete highlighted call-tree) 
          Version 1.53: June 17, 2011
                1. Bug fix related to appending cscope databases
                2. Bug fix related to loading xref databases
          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

         Version 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 "tree-display" 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
                 NOTE: defaults for tree-orientation set to vertical

          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
                   Functions inside macro definitions will be incorrectly
                   attributed to the top level calling function

  }}}
  {{{ Thanks:

   Ben Fritz                      (ver 1.53 -- Bug reports on database append/load)
   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.4 -- Testing/bug report/patches)
   Yegappan Lakshmanan            (Ver 0.2 -- Patches)

   The Vim Community, ofcourse :)
