cca.cxx

Go to the documentation of this file.

// cyclomatic complexity analyzer

//
// Copyright 2002, 2010, 2011 Lowell Boggs Jr.
//
// This file or directory, containing source code for a computer program,
// is Copyrighted by Lowell Boggs, Jr.  987 Regency Drive, Lewisville
// TX (USA), 75067.  You may use, copy, modify, and distribute this
// source file without charge or obligation so long as you agree to
// the following:
//
//  1.  You must indemnify Lowell Boggs against any and all financial
//      obligations caused by its use, misuse, function, or malfunction.
//      Further, you acknowledge that there is no warranty of any kind,
//      whatsoever.
//
//  2.  You agree not to attempt to patent any portion of this original
//      work -- though you may attempt to patent your own extensions to
//      it if you so choose.
//
//  3.  You keep this copyright notice with the file and all copies
//      of the file and do not change it anyway except language translation.
//
// You are responsible for enforcing your own compliance with these
// conditions and may not use this source file if you cannot agree to the
// above terms and conditions.
// 







#include <cxxtls/cpp_token_stream.h>
#include <cxxtls/file.h>
#include <cxxtls/fmtd.h>

#include <portable_math.h>
#include <portable_strstream.h>
#include <portable_io.h>
#include <cxxtls/options.h>

#include <cstdlib>
#include <fstream>
#include <iostream>
#include <algorithm>
#include <list>
#include <memory.h>
#include <iomanip>
#include <set>

using namespace std;
using namespace cxxtls;

static void parse_file(FileName const &);

static ostreambuf_iterator<char>* output;

static bool read_filenames_from_stdin = false; 
static bool log_all_tokens_to_stderr  = false; 
static bool log_filenames_to_stderr   = false; 
static bool grep_style_output         = true;  
static bool collapse_elseif           = true;  
static bool collapse_return           = true;  
static bool print_summary             = false; 
static bool print_functions           = true;  
static bool force_java_file           = false; 

static bool log_definitions           = false; 

static string ifKeyWord               ("if");
static string elseKeyWord             ("else");
static string whileKeyWord            ("while");
static string doKeyWord               ("do");
static string forKeyWord              ("for");
static string switchKeyWord           ("switch");
static string caseKeyWord             ("case");
static string defaultKeyWord          ("default");
static string operatorKeyWord         ("operator");
static string templateKeyWord         ("template");
static string classKeyWord            ("class");
static string structKeyWord           ("struct");
static string enumKeyWord             ("enum");
static string typedefKeyWord          ("typedef");
static string namespaceKeyWord        ("namespace");
static string usingKeyWord            ("using");
static string friendKeyWord           ("friend");
static string externKeyWord           ("extern");
static string publicKeyWord           ("public");
static string privateKeyWord          ("private");
static string protectedKeyWord        ("protected");
static string unionKeyWord            ("union");
static string typenameKeyWord         ("typename");
static string constKeyWord            ("const");
static string staticKeyWord           ("static");
static string catchKeyWord            ("catch");
static string tryKeyWord              ("try");
static string returnKeyWord           ("return");
static string throwKeyWord            ("throw");
static string extendsKeyWord          ("extends");  // Java only!
static string implementsKeyWord       ("implements"); // Java only!

static void printInfo(); // print a discussion of the algorithm.
static void printSummary();

static set<string> returnSynonyms;

static bool isJavaFile = false; // reset in parse_file on every file.

int main(int argc, char **argv, char **environ)
{

# ifdef _MSC_VER
  
    // force the output to be a binary stream and we'll control eht end of line sequencing our
    // selves
  
    cout.flush();
  
    setmode(1, O_BINARY);

# endif

  output = new ostreambuf_iterator<char>(cout);

  //
  // parse the options
  //

  ProgramOptions ops("-SO,-S,-R;-m,-info,-r,-e,-v,-files,-tokens,-stdin,-resume,-help,-h,--help,-j",
                     argc,
                     argv,
                     environ
                    );

  if(ops.option("-v"))
  {
    cout << "cca version 1.17" << endl;

      // revision history:
      //
      //  1.17 a.  Improved #if intereptation in order to eliminate
      //           the erroneous parsing of both the if and the else
      //           clauses.  Note that no real macro processing is going on
      //           in this change -- we are just making sure that we don't
      //           process both the if and the else.  Since header files
      //           often being with
      //
      //              #ifndef macroname
      //              #define macroname
      //                ...
      //              #endif
      //
      //           It is necessary for #ifndef to actually be taken.  However,
      //           most other #if tests will NOT be taken.  That is, generally
      //           we assume that the #if test fails except for the following:
      //
      //             #if 1  // is taken
      //             #if true // is taken
      //             #if TRUE // is taken
      //
      //           Almost all other tests are not.
      //
      //           This is just a way to eliminate duplicate code logic that really
      //           messes up the parser -- but it might mean your real code doesn't
      //           get parsed -- depending on how your #ifs work...
      //
      //           If you want REAL accuracy in macro expansion, create .E files
      //           and run cca.exe on them instead of the raw source.  For example:
      //           in your makefile add the following:
      //
      //               .c.E:
      //                   g++ -E $(CC_INCLUDES) $*.c >$@
      //            
      //
      //  1.16 a.  added support for class template specializations.
      //
      //  1.15 a.  Updated support for badly formed programs based on a common pattern
      //           in the boost library:  the use of a macro to generate a class name:
      //              struct MACRO(x) { ... }
      //
      //  1.14 a.  Added -j and fixed various bugs in c++ processing.
      //
      //  1.13 a.  Removed the need for the -dcl option
      //
      //  1.12 a.  Fixed major bug:  Now it is possible to correctly detect the
      //           following class name:
      //
      //              class CursorWindow::Dialog::Impl { ... }
      //
      //  1.11 a.  Add -dcl option to support vc++ goofiness
      //
      //  1.10 a.  Improved option mismatch detection.  -R doesn't go with -m or -r
      //
      //  1.9  a.  Fixed a bug in the handling of try/catch blocks
      //
      //  1.8  a.  added the "-SO" and "-S" option to trigger the printing of a summaries.
      //
      //  1.7  a.  added "-R returnSynonum" to allow you to define one or
      //           more synonyms for the return statement.  Typically this
      //           would be used to add "exit" as a synonym for return
      //           when -m and -r are not used.  Multiple -R's are allowed.
      //
      //  1.6  a.  fixed a bug in eat_template_parms to prevent it from walking
      //           across ;, {, or }.
      //
      //  1.5  a.  basic support for java, no thorough testing though.
      //           class static constructor method gets ignored for sure.
      //
      //  1.4  a.  array initializer value lists are no longer mistaken to
      //           function bodies.
      //
      //  1.3  a.  added -m option to more closely approximate the McCabe
      //           metric for if-else clasues.
      //       b.  added the -info option to print a discussion of the
      //           algorithm.
      //
      //  1.2  a.  add -e option to expand else-if complexity as it if were
      //           two statements instead of one (increasing CC number).
      // 
      //  1.1  a.  removed -defs option (its the only choice now).
      //       b.  added catch(){} block processing.  You can only get
      //           one executed at a time, so they define alternatives
      //           no sequences of code.  The largest pathcount will be
      //           the final pathcount after the blocks.
      //       c.  removed -nostats option (it made no sense in this program).
      //       d.  removed -grep option (default)
      //       e.  removed -resume option (it made no sense here)
      //
      //  1.0  everything basically works and else-if and switch
      //       cases are treated as single big structures, of which only
      //       one block will executed, rather than being separate structures
      //       in which any block could execute.  You get smaller path
      //       counts in 1.0 than you got in 0.9 for else-if and switch
      //       blocks.

    exit(0);
  }


  log_filenames_to_stderr   =  ops.option("-files");
  read_filenames_from_stdin =  ops.option("-stdin");
  log_all_tokens_to_stderr  =  ops.option("-tokens");
  collapse_elseif           = !ops.option("-e"); 
  collapse_return           = !ops.option("-r");
  print_summary             =  ops.option("-S") || ops.option("-SO");
  print_functions           = !ops.option("-SO");
  force_java_file           =  ops.option("-j");


  if(ops.option("-m"))
  {
     collapse_elseif = false;
     collapse_return = false;
  }

  if(ops.option("-info"))
  {
     printInfo();
     exit(0);
  }

  if( ops.option("-R") )
  {
      // there is at least one synonym for the return statement

      ProgramOptions::Option const &r = ops.option("-R");

      ProgramOptions::value_iterator first = r.begin(),
                                     last  = r.end();

      while(first != last)
      {
          string const &current = *first++;

          returnSynonyms.insert(current);
      }

  }

  if(    ( ops.option("-r") || ops.option("-m") || ops.option("-e") )
     &&  returnSynonyms.size() != 0
    )
  {
      cerr << "cxa.exe: ERROR: -R not compatible with -e, -r, or -m" << endl;
      exit(1);
  }


  if(ops.option("-help")  ||
     ops.option("--help") ||
     ops.option("-h")
    )
  {
    FileName program(ops.argv[0]);

    cerr << "Usage:" << endl
         << "  "     << program.basename()
         << "  [options] [.c and .h file names]" << endl
         << "Options:" << endl
         << " Basic Options" << endl
         << "  -info    print a description of the algorithm" << endl
         << "  -help    print this help message" << endl
         << "  -h       ditto" << endl
         << "  --help   ditto" << endl
         << "  -stdin   read the .c and .h file names from stdin" << endl
         << "           note:  one filename per line" << endl
         << "  -tokens  log all tokens to stderr" << endl
         << "  -files   log processed files to stderr" << endl
         << "  -S       add a summary to the output" << endl
         << "  -SO      produce ONLY summary output" << endl
         << " Logic modification settings" << endl
         << "   -m      McCabe mode.  Sets -e, -r, etc." << endl
         << "   -e      suppresses else-if collapsing" << endl
         << "   -r      suppreses return-statment collapsing in if-else clauses" << endl
         << "             * does not apply to else-if clauses!" << endl
         << "   -R syn  Define a synonym for 'return'" << endl
         << "             * syn usually names a function, like exit." << endl
         << "             * multiple -R syns are allowed" << endl
         << "             * not compatible with -e, -r, or -m" << endl
         << "Output Format:" << endl
         << " Example" << endl
         << "   filename.c:123:  ::main  S=20 P=8 C=3" << endl
         << " Explanation:" << endl
         << "   function ::main was defined in file \"filename.c\" at " << endl
         << "   line 123.  It has 20 statements with 8 paths through the" << endl
         << "   code, and has a cyclomatic complexity number of 3." << endl
         ;

    exit(0);
  }

  ops.argv.erase(ops.argv.begin());  // remove the program name from the
                                     // non-optional program arguments


  // get the list of file names to work on

  list<FileName> files;

  if(read_filenames_from_stdin)
  {
    string tmp;

    while(!cin.eof())
    {
      tmp.resize(0);

      getline(cin, tmp);

      if(tmp.size() == 0)
        break;
        
        
      files.push_back(tmp);

    }
  }
  else
  {
    size_t i;

    for(i=0; i < ops.argv.size(); ++i)
    {
      files.push_back(ops.argv[i]);
    }

  }

  // parse the named files

  list<FileName>::iterator l = files.begin();
  list<FileName>::iterator g = files.end();


  for(; l != g; ++l )
  {
    if(!l->exists())
    {
      cerr << *l << " error, file does not exist" << endl;
    }
    else
    if(!l->is_dir())
      parse_file(*l);
  }

  if(print_summary)
      printSummary();

  exit(0);
}

static void parse_declarations(CPP_Buffer_Token_Source &s);
static void log_symbol(string type, string name, string file, int line, bool include_scope=true);

class DefineHandler
: public CPP_Token_Stream_Prep
  //
  //
{
public:

  static vector<bool> ifStack_;

  static bool tokensVisible_;

  static void computeVisibility()
  {
      // even 1 false on the stack means tokens are not currently visible.

      tokensVisible_ = true;

      for(size_t i = 0; i < ifStack_.size(); ++i)
         if(!ifStack_[i])
         {
            tokensVisible_ = false;
         }

  }

  void ifHandler(string const &define, string const &file, int line) const
  {
      // assume define is not empty on entry

      static string ifKeyword("if");
      static string ifdefKeyword("ifdef");
      static string ifndefKeyword("ifndef");
      static string definedKeyword("defined");
      static string elseKeyword("else");
      static string endifKeyword("endif");

      char c = define[0];

      string name=define.substr(0,  define.find_first_of(" \t\n\r") );


      if(c == 'i')
      {
          if(name == ifKeyword)
          {
             bool computedVisibility = false;

             bool searchIt=true;

             for(size_t index = name.size(); index < define.size()-1; ++index)
             {
                char f = define[index];
                char n = define[index+1];

                static string trueKeyword("true");
                static string TRUEKeyword("TRUE");


                if(   (   ( f == '1' && isspace(n) )
                       || ( f == 't' && define.substr(index, 4) == "true")
                       || ( f == 'T' && define.substr(index, 4) == "TRUE")
                      )
                  )
                {
                   computedVisibility = true;
                   searchIt= false;
                   break;
                }

             }

             if(searchIt)
             {
                 string::const_iterator loc = search(define.begin(), 
                                                     define.end(), 
                                                     definedKeyword.begin(), 
                                                     definedKeyword.end()
                                                    );
                 
                 if(loc != define.end())
                 {
                     // defined is false, so we need to see if operation has been notted.
                 
                     while(loc != define.begin())
                     {
                        if(*loc == '!')
                        {
                           computedVisibility = true;
                           break;
                        }
                 
                        --loc;
                 
                     }
                 
                 }
             }

             ifStack_.push_back(computedVisibility);
          }
          else
          if(name == ifdefKeyword)
          {
             ifStack_.push_back(false);
          }
          else
          if(name == ifndefKeyword)
          {
             ifStack_.push_back(true);
          }

          computeVisibility();

      }
      else
      if(c == 'e')
      {
          if(name == elseKeyword)
          {
              if(!ifStack_.empty())
              {
                 ifStack_.back() = !ifStack_.back();
              }

          }
          else
          if(name == endifKeyword)
          {
              if(!ifStack_.empty())
                ifStack_.pop_back();

          }

          computeVisibility();
      }


  }

  void operator() (string const &define, string const &file, int line) const
  {
    string::const_iterator f(define.begin());
    string::const_iterator g(define.end());

    // only handle #defines

    if( f == g)
      return;

    if( *f != 'd')
    {
      return ifHandler(define, file, line);

      return;
    }
    // skip the word 'define'

    while(f != g && *f != ' ') ++f;

    // skip blanks after define

    while(f != g && (*f == ' ' || *f == '\n') ) ++f;

    if(f == g)
      return;  // missing define variable name

    // skip past the text in the define variable name

    string::const_iterator l(f);

    while(l != g &&
          (
            (*l >= 'a' && *l <= 'z') ||
            (*l >= 'A' && *l <= 'Z') ||
            (*l >= '0' && *l <= '9') ||
            (*l == '_')
          )
         ) ++l;

    // f,l now defines the name of the define variable

    static string define_name("define");

    log_symbol(define_name, string(f,l), file, line, false);

  }
};

vector<bool> DefineHandler::ifStack_;
bool DefineHandler::tokensVisible_ = true;

static void parse_file(FileName const& name)
//
// Parse a file and print out the definitions contained
// therein.
//
{
  if(force_java_file)
  {
     isJavaFile = true;
  }
  else
  {
     string ext = name.extension();
   
   
     if(ext == ".java" || ext == ".JAVA" )
     {
        isJavaFile = true; 
     }
     else
       isJavaFile = false;
  }

  FileContents buffer;

  name.slurp(&buffer);

  if(!buffer.ok())
  {
    cerr << "Error opening " << name << ", " << buffer.error() << endl << flush;
    exit(1);
  }

  DefineHandler dh;

  if(log_filenames_to_stderr)
    cerr << name << endl;

  CPP_Buffer_Token_Source s(buffer.begin(), buffer.end(), name, &dh);

  parse_declarations(s);

}

static CPP_Token                token;
static CPP_Buffer_Token_Source *stream;

class FunctionScope
{
public:

  typedef unsigned long long paths_t;   // 64 bit unsigned value holding the count of the
                                        // total number of paths through the code.

private:

   // keep these in sycn with the operator= method

   string scopeName;  
   string scopeMember;  // function name within the scope
   string scopeFile_;    // file where func location
   int    scopeLine_;    // line in scopeFile_ where func defined

   int    statements_;  // only applies to functions

   paths_t  paths_;       // only applies to functions

public:

   FunctionScope &operator=( FunctionScope const &rhs )
   {
     scopeName   = rhs.scopeName;
     scopeMember = rhs.scopeMember;
     scopeFile_   = rhs.scopeFile_;
     scopeLine_   = rhs.scopeLine_;

     statements_ = rhs.statements_;
     paths_      = rhs.paths_;


     return *this;
   }

   FunctionScope(FunctionScope const &rhs)
   {
      *this = rhs;
   }


   void resetCounters() 
      // go back to the state just before the { brace that starts
      // a function
   { 
      statements_ = 0;
      paths_      = 1;
      
   }

   FunctionScope()
   : scopeName()
   {
      scopeLine_   = 0;
      scopeMember.resize(0);
      scopeFile_.resize(0);

      resetCounters();
   }

   operator string const &() const { return scopeName; }

   string scopeMemberName() const { return scopeName + scopeMember; }

   string const &scopeMemberValue() const { return scopeMember; } 

   inline friend ostream &operator<<( ostream &os, FunctionScope const &me)
   {
      int CyclomaticComplexityNumber = int( 0.4999 + log2( me.paths_) );

      if(CyclomaticComplexityNumber < 1)
         CyclomaticComplexityNumber = 1;

      return os << me.scopeFile_ << ':' << me.scopeLine_      << ": "  
                << me.scopeName << me.scopeMember             << ' '
                << "S="        << me.statements_              << ' '  
                << "P="        << me.paths_                   << ' '
                << "C="        << CyclomaticComplexityNumber
                ;
   }

   void setScope(string const &s) { scopeName = s; }

   void setScopeMember(string const &m) { scopeMember = m; }
   
   void setScopeFileInfo(string const &file, int line) { scopeFile_ = file; scopeLine_ = line; }

   string const &scopeFile() const { return scopeFile_; }
   int           scopeLine() const { return scopeLine_; }

   string::const_iterator begin() const { return scopeName.begin(); }
   string::const_iterator end()   const { return scopeName.end(); }

   int      statements()    const { return statements_; }
   paths_t  paths()         const { return paths_;   }
   
   void addStatement()    { ++statements_; }

   void doublePaths()     
   {
       paths_t tmp(paths_);
   
       paths_ <<= 1;   

       if(paths_ < tmp)
       {
         // we should have been increasing the paths_ variable, not decreasing it
         // so we must have rounded off

         paths_ = paths_t(-1);  // truncate to the largest possible number

       }
   }

   void multiplyPaths( unsigned count)
   {
       paths_t tmp(paths_);
   
       paths_ *= count;

       if(paths_ < tmp)
       {
         // we should have been increasing the paths_ variable, not decreasing it
         // so we must have rounded off

         paths_ = paths_t(-1);  // truncate to the largest possible number

       }
   }

   void setPaths(paths_t count)   { paths_ = count; }

};

FunctionScope outer_scope;

struct SummaryData
{
    unsigned long int statements_;
    double            paths_;
    unsigned long int functions_;

    SummaryData()
    :  statements_(0)
    ,  paths_(0)
    ,  functions_(0)
    {
    }
};

map<string, SummaryData> summary;

static void printSummary()
{
   cout << "\nSUMMARY\n" << endl;

   cout << "INDIVIDUAL SCOPES" << endl;

   cout 
       << "\t" << "FUNCS"
       << "\t" << "CC#"
       << "\t" << "LOC"  
       << "\t" << "IN SCOPE" 
       << endl;

   map<string, SummaryData>::iterator next = summary.begin(),
                                      last = summary.end();


   SummaryData totals;

   int totalCC = 0;

   while(next != last)
   {
      string      const &name = next->first;
      SummaryData const &info = next->second;

      ++next;


      int CyclomaticComplexityNumber = int( 0.4999 + log2( info.paths_) );

      if(CyclomaticComplexityNumber < 1)
          CyclomaticComplexityNumber = 1;

      cout 
           << "\t" << info.functions_
           << "\t" << CyclomaticComplexityNumber 
           << "\t" << info.statements_ 
           << "\t" << name 
           << endl;

      totals.functions_  += info.functions_;
      totalCC            += CyclomaticComplexityNumber;
      totals.statements_ += info.statements_;
      totals.paths_      += info.paths_;

   }

   cout << "TOTALS" << endl;

   cout 
           << "\t" << totals.functions_
           << "\t" << totalCC
           << "\t" << totals.statements_ 
           << endl;


}


static void summarize()
{
    string scopeName = outer_scope;  // does not include the scope member

    SummaryData &data = summary[scopeName];

    data.paths_      += outer_scope.paths();
    data.statements_ += outer_scope.statements();
    ++data.functions_;
}



inline static void next_token()
//
// get the next token from the stream and leave it 'token'
//
{
  token.type_ = CPP_Token::eof;

  do
  {
      (*stream)(token);
  }
  while(!token.type_ == CPP_Token::eof && !DefineHandler::tokensVisible_);

  if(token.type_ == CPP_Token::aln &&
     token.text_[0] == 'o' &&
     token.text_ == operatorKeyWord
    )
  {
    (*stream)(token);

    if(token.type_ == '(')
    {
      token.type_ = CPP_Token::aln;

      token.text_ = operatorKeyWord + " " + token.text_;

      CPP_Token tmp;

      (*stream)(tmp);

      token.text_ += tmp.text_;
    }
    else
    {
      token.type_ = CPP_Token::aln;

      token.text_ = operatorKeyWord + " " + token.text_;
    }



  }
  else
  if(token.type_ == CPP_Token::inv && token.text_.find_first_of(';') < token.text_.size() )
  {
      // if some screwball conglomeration of tokens accidentally contains a semicolon,
      // call that token a semicolon because the tokenizer deals with token groups, not
      // just tokens.  So ;;;;;;, is not 5 ;'s but one ;;;;;;; token.  Though it is labeled
      // as invalid but that means only that it is invalid in C++.  Normally, C++, does not
      // conglomerate unrelated tokens together, but CPP_Token does.
      //
      // Anyway, multiple semicolons is a common enough error to specifically ignore it --
      // especially since ; plays such a key role in this tool.

      token.text_ = ";";
      token.type_ = ';';
  }


  if(log_all_tokens_to_stderr)
    cerr << token << " \t" << outer_scope.scopeMemberName() << endl;

}

inline bool eof()
//
// determine if we are at the end of the token stream
//
{
   return token.type_ == CPP_Token::eof;
}

static bool parse_declaration(bool log_func_forward_decls=false);



static void parse_declarations(CPP_Buffer_Token_Source &s)
//
// parse and print out all definitions in a file
// (don't use this for parsing nested stuff)
{
  stream = &s;

  for(next_token(); !eof(); )
  {
    outer_scope.setScope("::");

    if(parse_declaration())  // automatically calls next_token()
      break;
  }

  if(!eof())
  {
    cerr << token << ", error:  expected end of file" << endl;
    cerr << __FILE__ << ":" << __LINE__ << endl;
  }

}

#define ASSUMED_TOKEN(type) \
  if(token.type_ != type) \
  { \
    cerr << token << ", error:  expected " << CPP_Token::type_name(type) << endl; \
    cerr << __FILE__ << ":" << __LINE__ << endl; \
    return true; \
  }



// all parsing functions leave the token that terminated them
// in the input stream.

static bool parse_class();
static bool parse_namespace();
static bool parse_typedef();

static bool parse_enum();
static bool parse_extern();
static bool parse_using();
static bool parse_funcvar(bool log_forward_funcs_defs=false,
                          bool handling_typedefs=false);
static void eat_template_parms();
static void eat_curly_block();
static void eat_function_body();

static bool parse_declaration(bool log_func_forward_decls)
{
  if(token.type_ == ';' ) // allow randomly placed semicolons
  {
    next_token();
    return false;
  }

  if(token.type_ == '{')
  {
    // allow randomly placed {} blocks

    eat_curly_block();
    next_token();
    return false;

  }

  if(token.type_ == CPP_Token::eof)
    return true;

  if(token.type_ == '=')  // handle oddly placed variable initializations
  {
     while(token.type_ != ';')
     {
       if(token.type_ == '{')
         eat_curly_block();

       next_token();
     }

     return false;
  }


//  if(token.type_ != CPP_Token::der)
//    ASSUMED_TOKEN(CPP_Token::aln);

  if(token.text_ == templateKeyWord)
  {
    // eat template<parms>

    next_token();  // eat 'template'

    eat_template_parms();

    // now all references to the template keyword and its parms are
    // gone fromthe stream

  }

  if(token.text_ == classKeyWord  || token.text_ == structKeyWord || token.text_ == unionKeyWord)
    return parse_class();
  else
  if(token.text_ == typedefKeyWord )
    return parse_typedef();
  else
  if(token.text_ == enumKeyWord )
    return parse_enum();
  else
  if(token.text_ == namespaceKeyWord )
    return parse_namespace();
  else
  if(token.text_ == usingKeyWord )
    return parse_using();
  else
  if(token.text_ == externKeyWord)
    return parse_extern();
  else
  if(token.text_ == friendKeyWord)
  {
    next_token(); // eat the friend keyword

    if((token.type_ == CPP_Token::aln) &&
       (token.text_ == classKeyWord ||
        token.text_ == structKeyWord
       )
      )
    {
      // prevent a misnaming of the scope caused by the
      // parsing of friend declarations.

      while(token.type_ != ';')
        next_token();
    }

    return parse_declaration(log_func_forward_decls);

  }
  else
  if(token.type_ == CPP_Token::aln &&
     token.text_[0] == 'p'         &&
       (token.text_ == publicKeyWord    ||
        token.text_ == privateKeyWord   ||
        token.text_ == protectedKeyWord
       )
    )
  {
    //
    // eat the public:, private:, and protected: syntax so as not
    // to confuse the 'public: typedef int x' as a variable definition.
    //
    next_token();

    if(token.type_ == ':')
      next_token();

    return false;
  }
  else
    return parse_funcvar(log_func_forward_decls);

}


static void log_symbol(string type, string name, string file, int line, bool include_scope)
{

  if(!log_definitions)
     return;

  // the file parameter is unused unless we are doing grep style output

  if(name.size() != 0)
  {
    if(grep_style_output)
    {
      char buffer[40];

      sprintf(buffer, "%d", line);

      copy(file.begin(), file.end(), *output);
      *(*output)++ = ':';

      copy(buffer, buffer + strlen(buffer), *output);
      *(*output)++ = ':';

      *(*output)++ = ' ';

      copy(type.begin(), type.end(), *output);
      *(*output)++ = ' ';

      if(include_scope)
      {
        if(name.begin() != name.end() && *name.begin() != ':')
            copy(outer_scope.begin(), outer_scope.end(), *output);  // only symbols not in the global scope,
                                                                    // prefix them with their scope
      }

        
      copy(name.begin(), name.end(), *output);


      *output = copy_end_of_line(*output);

    }
    else
    {

      *(*output)++ = '-';

      copy(type.begin(), type.end(), *output);
      *(*output)++ = ' ';

      if(include_scope)
      {
        if(name.begin() != name.end() && *name.begin() != ':')
            copy(outer_scope.begin(), outer_scope.end(), *output);  // only symbols not in the global scope,
                                                                    // prefix them with their scope
      }
        
      copy(name.begin(), name.end(), *output);
      *(*output)++ = ' ';

      char buffer[40];

      sprintf(buffer, "%d", line);

      char *scan = buffer;

      while(*scan)
        *(*output)++ = *scan++;

      *output = copy_end_of_line(*output);

    }
  }

  cout.flush();

}

struct ScopeBinder
//
//
{
  FunctionScope saved_scope; 

  ScopeBinder(string new_scope)
  {
    saved_scope = outer_scope;
    outer_scope.setScope(new_scope);
  }

  ~ScopeBinder()
  {
    outer_scope = saved_scope;

  }

};


static void parse_variables_defined(bool log_func_forward_decls=false,
                                    bool handling_typedefs=false
                                   )
// parse and log the names of variables defined as part of a struct
// declaration:
//
//   struct x { ... }  var1, *var2, function(..), array[...], ... ;
{

  if(token.type_ != ';')
    parse_funcvar(log_func_forward_decls, handling_typedefs);

  return;

}
static void eat_function_parms(string *parmtext=0);




static bool parse_class()
//
//  parse class, union, and struct declarations and keep track
//  of the name of the 'scope' of each nested class
//
{


  string class_type = token.text_;

  next_token();  // eat the 'struct' or 'class' keyword


  string name = token.text_;  // save the class name
  string file = token.file_;
  int    line = token.line_;
  bool   maybeFunc = false;

  if(token.type_ == CPP_Token::der)
  {
      // handle this:
      //
      //  class ::SomeClass { ... }

      next_token();

      ASSUMED_TOKEN(CPP_Token::aln);

      name += token.text_;
      line  = token.line_;

  }


  if(token.type_ == '{')
  {
    name="unnamedstruct"; // handle struct { ... }
  }
  else
  {
      if(token.type_ == '[')
      {
        // someone in plain old c has defined int class[470];
        
        int depth=0;
        
        while(!eof())   // eat the contents of the arrays
        {
          if(token.type_ == '[')
            ++depth;
          else
          if(token.type_ == ']')
          {
            --depth;
            if(depth == 0)
              break;
          }
          next_token();
        }

        next_token();  // eat the closing ]
        
      }
      else if(token.type_ == '(')
      {
        // oops, someone in plain old C has done this:  int class() ...
        
        eat_function_parms();
        next_token();
      }


      if(token.type_ == ';' || token.type_ == ',' )
      {
          // we are not parsing a real class definition
          // but rather a plain old c style variable
          // declaration like 'int class;'
          next_token();
          return false;
      }

    ASSUMED_TOKEN(CPP_Token::aln);
   
    while(token.type_ == CPP_Token::aln)
    {

        next_token(); // should get here at least once

        if(token.type_ == CPP_Token::aln)
        {

           if(isJavaFile && token.text_ == extendsKeyWord)
              break;

           maybeFunc=true;

           // Assume we parsing something like this:
           //
           //   class MACRO ClassName {... }
           //               ^
           //
           // But we also have to support this:
           //
           //   class SomeClass  function() { return SomeClass(); }
           //                    ^
           //
           // And this
           // 
           //   class MACRO RealClassName { ... }
           //               ^

           name = token.text_;  // save the class name
           file = token.file_;
           line = token.line_;
        }
        else
        if( maybeFunc && token.type_ == ';' )
        {
           // log_symbol("variable", name, file, line);
           return false;
        }

    }

    while(token.type_ == CPP_Token::der)
    {
       // handle NAME::NAME::NAME... as the class name, as in
       //
       //   class CursorWindow::Dialog::Impl { ... }

       name += token.text_;
       line  = token.line_;
       next_token();


       if(token.type_ != CPP_Token::aln)
         break;

       name += token.text_;
       line  = token.line_;
       next_token();

    }


  }


  if(token.type_ == ';')
    return false;

  if(    (    token.type_ == CPP_Token::aln 
          &&  token.text_ != extendsKeyWord
          &&  token.text_ != implementsKeyWord
         )
     ||  token.type_ == '&'            
     ||  token.type_ == '*'
    )
  {
    // this is a variable declaration such as when some does this
    // in plain old c   typedef int class;   class &v1, *v2, x;

    parse_variables_defined();

    return false;

  }


  if(token.type_ == '(')
  {
      // we have something like this:
      //
      //   class something(...) ...
      
      eat_function_parms(); 

      if(token.type_ == ')')
      {
        next_token();

        if(maybeFunc)
        {
            if(token.type_ == '{' ||
               token.type_ == ';' ||
               (token.type_ == CPP_Token::aln && token.text_ == "const")
              )
            {
                // we have something like this:
                //
                //  class  ClassName  functName() const { ... }
                //                                ^     ^
                // we are not defining a class, we are defining a function

                while(   token.type_  != CPP_Token::eof
                      && token.type_  != ';'
                      && token.type_  != '{'
                      && token.type_  != '}'
                     )
                {
                   next_token(); // skip till { or end of declaration

                }

                if(token.type_ == CPP_Token::eof)
                   return true;

                if(token.type_ == '{')
                {

                    outer_scope.setScopeMember(name);
                    outer_scope.setScopeFileInfo(file, line);

                    eat_function_body();

                    if(token.type_ == '}')
                       next_token();
                   
                }

                return false;

            }
             
        }

      }
    
      
      // assume we are seeing something like this:
      //
      //   class compiler_directive(parms)   name { ...
      
      if(token.type_ == CPP_Token::aln || token.type_ == CPP_Token::der)
      {
          name = token.text_;  // save the class name
          file = token.file_;
          line = token.line_;
      }
      
      if(token.type_ == CPP_Token::der)
      {
          // we are seeing this:
          //
          //   class directive(parms) ::name ...

          next_token();

          if(token.type_ == CPP_Token::aln)
          {
             name += token.text_;
             line  = token.line_;
          }

          next_token();

      }
      else
      {
        if(token.type_ == '<')
        {
           eat_template_parms();
           if(token.type_ == '>')
              next_token();
        }


        if(   token.type_ == '{' 
           || token.type_ == ':'
          )
          {
            // user has done something like this
            //   class function(parms) { .. }
            //                         ^
            // Normally, this is a syntax error, but if function
            // is really a macro that computes the class name, then, mabye
            // we want to not complain about it...

            if(token.type_ == ':')
              {
                while(   token.type_ != ';'
                      && token.type_ != '{'
                      && token.type_ != CPP_Token::eof
                     )
                  {
                    next_token(); // consume tokens until { or ;
                  }
              }


          }
        else
        if(token.type_ == ';')
        {
             next_token();
             return false; // forward decl of badly formed class def
        }
        else
        if(token.type_ == CPP_Token::der)
        {
           // we are seeing someting like this:
           //   struct Macro(parms)<parms>  ::result<templateParms> : baseMacro(parms) {};
           //                               ^
           //
           // this is a multi-level specialization

           name=""; // we are going to reconstruct the name to refer to result

           while(token.type_ == CPP_Token::der)
           {
              next_token();
              
              ASSUMED_TOKEN(CPP_Token::aln);

              name+= token.text_;
              line = token.line_;
              file = token.file_;

              next_token();
           }

        }
        else
        {
            ASSUMED_TOKEN(CPP_Token::aln);
            next_token();
        }


      }

      while(token.type_ == CPP_Token::der)
      {
         name += token.text_;
         line  = token.line_;
         next_token();

         if(token.type_ != CPP_Token::aln)
            break;

         name += token.text_;
         line  = token.line_;

         next_token();

      }

      // At this point, we are here:
      //
      //   class directive(name) ::name::name::name ...
      //                                            ^

  }
  else
  if(token.type_ == '<')
  {
      // we have something like
      //
      //   template<> struct Class<instanceParms> { ... };

      eat_template_parms();
      if(token.type_ == '>')
         next_token();
     
  }


  // now we know that we really are in a normal c++ class
  // union, or struct declaration.  The classname now gets
  // the added to the scope.


  log_symbol(class_type, name, file, line);

  string newScope;

  static string colon_colon("::");


  if(name[0] != ':')
  {
      newScope = string(outer_scope) + name + colon_colon;
  }
  else
  {
     newScope = name + colon_colon;
  }

  ScopeBinder saved_scope(newScope);

  while(!eof() && token.type_ != '{' && token.type_ != ';' )
    next_token();

  if(token.type_ == ';')
  {
     next_token();
     return false;
  }


  if(eof())
    return true;


  next_token();

  while(token.type_ != '}')
  {
    if(token.type_ == '~')   // destructors mess up the parse_declaration logic
    {
      next_token();
      
      if(token.type_ == CPP_Token::aln)
      {
          static string tilde("~");

          token.text_ = tilde + token.text_;
      }

    }

    if(parse_declaration(true))
      return true;
  }

  next_token();

  outer_scope = saved_scope.saved_scope;

  parse_variables_defined();  // as part of this class declaration

  return false;

}

static void eat_type_name()
//
// parse and discard a typename -- particularly it handles
// the unsigned type's bizare variants.
//
{
  while(token.type_ == CPP_Token::aln &&
        ( (token.text_ == typenameKeyWord) || (token.text_ == constKeyWord) )
       )
  {
    next_token();
  }

  if(token.text_ == "unsigned")
  {
    next_token();

    if(token.type_ == CPP_Token::aln &&
       (token.text_ == "int"    ||
        token.text_ == "short"  ||
        token.text_ == "long"   ||
        token.text_ == "char"
       )
      )
        next_token();
  }
  else
  {
    do
    {
      next_token();
    }
    while(token.type_ == CPP_Token::der);

  }

  eat_template_parms();  // if this is a template type name eat the parms

  while(   (!eof() && token.type_ == '*') 
        || (token.type_ == '&' )
        || (token.type_ == CPP_Token::aln && token.text_ == constKeyWord)
       )
  {
    next_token(); // eat normal type modifiers
  }

}


static bool parse_typedef()
{
  next_token();  // eat the word 'typedef'

  if(token.text_ == classKeyWord || token.text_ == structKeyWord || token.text_ == unionKeyWord)
    return parse_class();

  if(token.text_ == enumKeyWord)
    return parse_enum();

  eat_type_name();

  parse_variables_defined(false, true);
                                        

  return false;
}

static bool parse_enum()
//
//  parse and log enumeration declarations
//
//    enum { ... } variables
//    enum name {  ... } variables
//    enum name variables
//    enum [name] { name [=value,]... } [variables]
//
{

  next_token();  // eat 'enum'

  CPP_Token save = token;

  next_token();

  if(token.type_ == '{')
  {
    static string enum_type(enumKeyWord);
    static string enum_value("enumeration");

    log_symbol(enum_type, save.text_, save.file_, save.line_);

    // parse { name [=value, ...] }

    next_token();  // eat '{'

    while(token.type_ != '}')
    {
       if(token.type_ == CPP_Token::aln)
       {
         log_symbol(enum_value, token.text_, token.file_, token.line_);
        
         next_token();
        
         if(token.type_ == '=')
         {
           // eat initializer
        
           while(!eof() && token.type_ != ',' && token.type_ != '}')
             next_token();
        
         }
        
       }
       else
         next_token();
    }

    next_token();  // eat the closing '}'

  }

  parse_variables_defined();

  return false;
}
static bool parse_namespace()
  //
  // handle namespace [optional name] ;
  //
{
  next_token();

  ScopeBinder old_scope(outer_scope);

  if(token.type_ == CPP_Token::aln)
  {
    // outer_scope += token.text_ + "::" ;

    string newName = string(outer_scope) + token.text_ + "::";

    outer_scope.setScope(newName);

    next_token();
  }
  else
  {
    outer_scope.setScope("<filescope>::");
  }

  if(token.type_ == '{')
  {
     next_token();

     while(!eof() && token.type_ != '}')
     {
       if(parse_declaration())
         return true;
     }

     next_token(); 

     return false;

  }

  return parse_declaration();

}
static bool parse_using()
//
// handle using namespace ;
// or     using namespace::KeyWord ;
//
{
  next_token();  // eat 'using'

  bool is_namespace(false);

  if(token.text_ == namespaceKeyWord)
  {
    next_token();
    is_namespace = true;
  }

  CPP_Token tmp(token);

  tmp.text_.resize(0);

  while(!eof() && token.type_ != ';')
  {
    if(token.type_ == CPP_Token::aln ||
       token.type_ == CPP_Token::der
      )
    {
      tmp.text_ += token.text_;
    }

    next_token();
  }

  next_token(); // eat the semicolon

  static string used_symbol("used");

  if(!is_namespace && tmp.text_.size())
    log_symbol(used_symbol, tmp.text_, tmp.file_, tmp.line_);

  return false;
}

static void eat_parenthesis()
//
//  Assuming that the current token is placed immediately after
//  an open parenthesis, consume text until a closing parentheis
//  is found.  If the current token is a closing parenthesis, 
//  it terminates immediately.
//
//  Nested parenthecals are skipped in the process.
// 
//  leading parenthesis should be in the stream.  trailing paren
//  will be left in the stream
{
  int depth=0;

  while(!eof())
  {
     if(token.type_ == '(')
       ++depth;
     else
     if(token.type_ == ')')
     {
       --depth;
       if(depth == 0)
       {
         break;
       }
     }

     next_token();
  }
}

static void eat_curly_block()
//
// ignore all tokens between matching {}'s.
// (leaves '}' in the stream)
//
{
  int depth=0;

  while(!eof())
  {
     if(token.type_ == '{')
       ++depth;
     else
     if(token.type_ == '}')
     {
       --depth;
       if(depth == 0)
       {
          break;
       }
     }

     next_token();
  }

//  cout << "EXITING CURLY BLOCK: " << token.file_ << " " << token.line_ << endl;

}

static void eat_till_semicolon()
  // and the semicolon too.
{
    while(    token.type_ != CPP_Token::eof 
          &&  token.type_ != ';'   
          &&  token.type_ != '}'
          &&  token.type_ != '{'

          &&  !(    token.type_ == CPP_Token::aln 
                 && (     token.text_ == ifKeyWord 
                     ||   token.text_ == elseKeyWord
                     ||   token.text_ == whileKeyWord
                     ||   token.text_ == forKeyWord
                     ||   token.text_ == doKeyWord
                     ||   token.text_ == caseKeyWord
                     ||   token.text_ == defaultKeyWord
                     ||   token.text_ == switchKeyWord
                    )
               )

        )
    {
      next_token();
    }

    while(token.type_ == ';')
       next_token();
}

struct ElseifCounterInfo
{
   int                    count_;
   FunctionScope::paths_t maxPaths_;   // largest encountered
   FunctionScope::paths_t basePaths_;  // start of if-else sequence

};


static bool process_statement(ElseifCounterInfo *);

static void  eat_case_blocks()
   //
   //  Consume statements and tokens until we encounter end of file or }
   //
   //  return the count of case and default keywords found.
   //
   //  leave the path count of the scope set to the largest path count of any
   //  block.
   //
{

   unsigned cases=0;

   FunctionScope::paths_t startPathCount   = outer_scope.paths();
   FunctionScope::paths_t largestPathCount = outer_scope.paths();

   while(    token.type_ != CPP_Token::eof
         &&  token.type_ != '}'
        )
   {
      // loop assumes that the current value of outer_scope.paths() is or has
      // been forced to be startPathCount

      if(    token.type_ == CPP_Token::aln
         &&  (   token.text_ == caseKeyWord
              || token.text_ == defaultKeyWord
             )
        )
      {
         ++cases;
         
         if( outer_scope.paths() > largestPathCount )
         {
            largestPathCount = outer_scope.paths();
         }

         outer_scope.setPaths( startPathCount );

         while(    token.type_ != ':' 
               &&  token.type_ != '}'
               &&  token.type_ != CPP_Token::eof
              )
         {
            next_token();
         }

         if(token.type_ == ':')
            next_token();

         // we are past the 'case id :' or the 'default :' part and
         // ready to process statements.

         while(    token.type_ != CPP_Token::eof
               &&  token.type_ != '}'
               && !(
                       token.type_ == CPP_Token::aln
                    && (
                           token.text_ == caseKeyWord
                        || token.text_ == defaultKeyWord
                       )
                   )
              )
         {
            process_statement(0);  // process statements that don't affect the 
                                  // logic of the switch clause we are in
         }
              
         

      }
      else
         process_statement(0); // ignoring 'return' flag here.  Don't see how we could use it
                              // yet

   }

   if(largestPathCount > outer_scope.paths())
   {
     outer_scope.setPaths(largestPathCount);
   }
   
   outer_scope.multiplyPaths(cases);

}

static bool process_statement(ElseifCounterInfo *elseifCounter)
   // and remove the trailing terminal:  ; or }
   //
   // return true only if the last executable thing in the statement
   // was a return directive.  For non-block statements, of course this
   // simply means that the statement was a return statement.  For block
   // statements, "{...}", it means that the last statement before the }
   // was a return.
{

    // Warning:  do not return early from this function, always drop through
    // the bottom!  

    bool returnWasLastStatement = false;

    if( token.type_ == '{')
    {
        next_token();

        while(    token.type_ != CPP_Token::eof
              &&  token.type_ != '}'
             )
        {
           returnWasLastStatement = process_statement(0);
        }

        if(token.type_ == '}')
            next_token();

        // we have consumed leading and trailing } and all statements within.

    }
    else
    if(token.type_ == CPP_Token::aln)
    {

       if( token.text_ == ifKeyWord )
       {
          outer_scope.addStatement();

          ElseifCounterInfo myInfo;

          myInfo.count_     = 0;
          myInfo.maxPaths_  = outer_scope.paths();
          myInfo.basePaths_ = outer_scope.paths();

          if(elseifCounter == 0 || (!collapse_elseif) )
          {
             elseifCounter = &myInfo;
          }

          ++elseifCounter->count_;

          next_token();

          eat_parenthesis();

          if(token.type_ == ')')
            next_token();

          bool oneSideReturned = false;

          // handle the if-clause

          if(process_statement(elseifCounter))
             oneSideReturned = true;

          if( outer_scope.paths() > elseifCounter->maxPaths_)
             elseifCounter->maxPaths_ = outer_scope.paths();

          outer_scope.setPaths(elseifCounter->basePaths_);

          // if we have an else clause, handle it
          
          if(   token.type_ == CPP_Token::aln 
             && token.text_ == elseKeyWord
            )
          {
             next_token();
          
             if(process_statement(elseifCounter))
                oneSideReturned = true;

             if(outer_scope.paths() > elseifCounter->maxPaths_)
                elseifCounter->maxPaths_ = outer_scope.paths();

          }

          outer_scope.setPaths(elseifCounter->maxPaths_);

          if(elseifCounter->count_ == 1 )
          {
             // this is not an if-else-if sequence

             if(!oneSideReturned)
                outer_scope.doublePaths();
          }
          else
          if(elseifCounter->count_)
          {
            // we have not yet handled this elseifCounter's count of paths

             outer_scope.setPaths( (1 + elseifCounter->count_) * outer_scope.paths() );

             elseifCounter->count_ = 0; // suppress further processing thereof.
          }

       }
       else
       if(token.text_ == elseKeyWord)
       {
         // we should never get here, it indicates a random else in
         // the code

         cerr << "Error:  "
              << token.file_ << ":" << token.line_
              << ": unexpected else keyword" 
              << endl;


         next_token();

         returnWasLastStatement = process_statement(0);

       }
       else
       if(    token.text_ == whileKeyWord 
          ||  token.text_ == forKeyWord
         )
       {
          outer_scope.addStatement();
          outer_scope.doublePaths();


          next_token(); // skip while, for, or switch token

          eat_parenthesis();

          if(token.type_ == ')' )
          {

              next_token();  // eat the trailing parenthesis
              
          }

          process_statement(0);  // does not affect returnWasLastStatement
                                // because these are looping constructs.

       }
       else
       if( token.text_ == doKeyWord)
       {
          next_token();

          process_statement(0); // does not affect returnWasLastStatement

          if(    token.type_ == CPP_Token::aln
             &&  token.text_ == whileKeyWord
            )
          {
             outer_scope.addStatement();

             // we have your standard do...while construct folks, nothing to see, move a long, move a long

             next_token(); // eat the while

             eat_parenthesis();

             if( token.type_ == ')')
               next_token();

             outer_scope.addStatement();
             eat_till_semicolon(); // and the semicolon too
             outer_scope.doublePaths();

          }
       }
       else
       if( token.text_ == switchKeyWord  )
       {
           next_token();  // eat 'switch'

           if(token.type_ != '(')
           {
             cerr << "Error:  "
                  << token.file_ << ":" << token.line_
                  << ": expected '(' after 'switch' " 
                  << endl;
           }
           else
           {

             eat_parenthesis();

             if( token.type_ == ')')
               next_token();

             outer_scope.addStatement();

             if(token.type_ != '{')
             {
                 cerr << "Error:  "
                      << token.file_ << ":" << token.line_
                      << ": expected '{' after 'switch()'" 
                      << endl;

             }
             else
             {
                 next_token();  // eat the leading{

                 eat_case_blocks(); // leave trailing } in the token

                 if(token.type_ != '}')
                 {
                     cerr << "Error:  "
                          << token.file_ << ":" << token.line_
                          << ": expected '}' after 'switch() { ... case ... '" 
                          << endl;
                 }
                 else
                 {
                    next_token();  // eat the trailing }
                 }


             }

           }
           
       }
       else
       if(   token.text_ == caseKeyWord
          || token.text_ == defaultKeyWord
         )
       {
         cerr << "Error:  "
              << token.file_ << ":" << token.line_
              << ": expected keyword: " 
              << token.text_
              << endl;

         while(token.type_ != CPP_Token::eof
               && token.type_ != ':'
              )
         {
             next_token(); 
         }

         if(token.type_ == ':')
           next_token();

       }
       else
       if(token.text_ == catchKeyWord )
       {
          FunctionScope::paths_t basePaths = outer_scope.paths();
          FunctionScope::paths_t maxPaths  = outer_scope.paths();

          do
          {
             outer_scope.setPaths(basePaths);

             outer_scope.addStatement();  // catch is a statement because
                                          // code gets generated.

             next_token();  //eat 'catch'

             if(token.type_ != '(')
             {
                
                 cerr << "Error:  "
                      << token.file_ << ":" << token.line_
                      << ": unexpected token, '" 
                      << token.text_
                      << "'"
                      << endl;

                 break;
             }

             eat_parenthesis();

             if( token.type_ == ')')
               next_token();

             process_statement(0); // should be a curly for valid
                                   // syntax, but we only claim to work
                                   // on valid syntax...


             if(outer_scope.paths() > maxPaths)
                maxPaths = outer_scope.paths();

          }
          while(    token.type_ == CPP_Token::aln
                &&  token.text_ == catchKeyWord
               );

          outer_scope.setPaths(maxPaths);
       }
       else
       if(token.text_ == tryKeyWord)
       {
          next_token();  // eat the try keyword

          if( token.type_ != '{')
          {
             cerr << "Error:  "
                  << token.file_ << ":" << token.line_
                  << ": unexpected token, '" 
                  << token.text_
                  << "', expected '{'"
                  << endl;

          }
          else
          {
             process_statement(0); // eat the try clause

             while(   token.type_ == CPP_Token::aln 
                   && token.text_ == catchKeyWord
                  )
             {
                 process_statement(0); // eat the catch clause
             }

          }
         
       }
       else
       {
          outer_scope.addStatement();

          if(   collapse_return
             && token.type_ == CPP_Token::aln
             && (    token.text_ == returnKeyWord
                 ||  token.text_ == throwKeyWord
                 ||  (   returnSynonyms.find(token.text_) 
                      != returnSynonyms.end() 
                     )
                )
            )
          {
            returnWasLastStatement = true;
          }

          // not call outer_scope.doublePaths() here.  Instead, we need to count the number
          // of the cases/defaults in this switch statement and multipley the path count by
          // that number rather than using the number 2 and most certainly, do not double
          // the path count on ever case/default.

          eat_till_semicolon(); // and the semicolon too
       }

    }
    else
    {
      outer_scope.addStatement();
      eat_till_semicolon(); // and the semicolon too
    }

    return returnWasLastStatement;
}


static void eat_function_body()
//
// process all statements in a function body.  The trailing } as the current
// token when the function exits.
//
{
  string const &funcName = outer_scope.scopeMemberValue();

  if(    funcName == ifKeyWord
     ||  funcName == whileKeyWord
     ||  funcName == forKeyWord
     ||  funcName == switchKeyWord
     ||  funcName == catchKeyWord
    )
  {
     cerr << outer_scope.scopeFile() 
          << ":" 
          << outer_scope.scopeLine() 
          << ":  mismatched { ... } earlier in function"
          << "\n   check for #if blocks with unmatched { or }"
          << endl;
  }


  FunctionScope savedscope(outer_scope);

  outer_scope.resetCounters();

  next_token();  // we would not get here if we were not already sitting on a {

  while(    token.type_ != CPP_Token::eof
        &&  token.type_ != '}'
       )
  {
      process_statement(0);
  }

  if(token.type_ == '}')
     next_token();

  outer_scope.setScope( string(savedscope) );
  outer_scope.setScopeMember( savedscope.scopeMemberValue() );
  outer_scope.setScopeFileInfo(savedscope.scopeFile(), savedscope.scopeLine() );

  if(print_functions)
      cout << outer_scope << endl;

  if(print_summary)
      summarize();

  while(    token.type_ == CPP_Token::aln
        &&  token.text_ == catchKeyWord
       )
  {
     eat_till_semicolon(); // will stop on the leading {

     process_statement(0);  // at the catch body

  }

}




static void eat_function_parms(string *parmtext)
//
// ignore all tokens between matching ()'s.
// (leaves ')' in the stream).  The first alphanumeric
// token between the paren's is stuck in parmtext if
// non-zero
//
{
  int depth=0;

  while(!eof())
  {
     if(token.type_ == '(')
       ++depth;
     else
     if(token.type_ == ')')
     {
       --depth;
       if(depth == 0)
         return;
     }

     if(parmtext && depth == 1 && token.type_ == CPP_Token::aln)
     {
       *parmtext = token.text_;
       parmtext = 0;
     }

     next_token();
  }

}

static void eat_template_parms()
  // parse and discard template parms
  //
  // that is:   < stuff, more_stuff< a, b, c>, ... >
  // Also handles:
  //
  //   class templatename< ... >
  //
{

  int depth=0;

  if(token.type_ == CPP_Token::aln &&
     token.text_ == classKeyWord
    )
  {
    next_token();  // eat 'class' keyword
    next_token();  // eat template specialization name
  }

  if(token.type_ != '<')
    return;

  while(!eof())
  {
     if(    token.type_ == ';' 
        ||  token.type_ == '{'
        ||  token.type_ == '}'
       )
     {
         break;
     }

     if(token.type_ == '<')
       ++depth;
     else
     if(token.type_ == '>')
     {
       --depth;
       if(depth == 0)
         return;
     }

     next_token();
  }


}

static bool parse_funcvar(bool log_forward_func_declarations,
                          bool handling_typedefs
                         )
//
// parse all function and variable declarations -- and handle
// any leftover trash that occurs whenever you are parsing
// something that is not strictly syntactically correct.
//
// So instead of defining a function like this:
//
//    int function(parms) { body }
//
// This code will accept
//
//    trash ... trash int trash trash ... function(parms) trash .. trash { ... }
//
// It will also parse handle things like this:
//
//    trash struct { members } varname ;
//
// The 'trash' that is excepted includes pretty much any random tokens
// and when '[', '{', the text up to the corresponding closing token
// is simply ignored.
//
{
  // scan tokens until you first encounter one of
  //  (, [, {, struct/class/union/template or ;
  // that tells you that you are defining.

  CPP_Token tmp; // save token just before terminator

  if(token.text_ == staticKeyWord)
    next_token();

  do
  {



    if(token.type_ == '{')
    {
      // some bizarre code fragment we misunderstood

      eat_curly_block();

      if(token.type_ == '}')
          next_token();  // eat the trailing '}'


      if(token.type_ == ',')
      {
          static string unknown_type("unknown");
        
          next_token();
          log_symbol(unknown_type, tmp.text_, tmp.file_, tmp.line_);
          return parse_funcvar();
      }
      return false;

    }

    if(token.type_ == CPP_Token::aln)
    {
      if(token.text_ == structKeyWord   ||
         token.text_ == classKeyWord    ||
         token.text_ == unionKeyWord    ||
         token.text_ == templateKeyWord ||
         token.text_ == externKeyWord
        )
        return parse_declaration();

      tmp = token;

      next_token();

      if(token.type_ == '<')
      {
        eat_template_parms();
      }

    }
    else
    if(token.type_ == '=')
    {
      // scoop up and ignore a variable initializer

      while(token.type_ != ',' &&
            token.type_ != ';' &&
            !eof()
           )
      {
        if(token.type_ == '{')
          eat_curly_block();
        else
        if(token.type_ == '(')
          eat_function_parms();
        
        next_token();
      }


    }
    else
    if(token.type_ == '>')
    {
       next_token();

       if(token.type_ == ';')
       {
          next_token();
          return false;   // handle extern template<parms>; which forces instantiation of a signature
       }
    }
    else
      next_token();

    if(token.type_ == '~')
    {
      next_token();

      if(token.type_ == CPP_Token::aln)
      {
        static string tilde("~");
        
        token.text_ = tilde + token.text_;
      }

    }

    while( token.type_ == CPP_Token::der) // ::
    {
      next_token();

      if(token.type_ == '~')
      {
        next_token();

        if(token.type_ == CPP_Token::aln)
        {
          static string tilde("~");
        
          token.text_ = tilde + token.text_;
        }

      }

      if(token.type_ != CPP_Token::aln)
        break;
        
      tmp.text_ += "::";
      tmp.text_ += token.text_;
      tmp.line_  = token.line_;

      next_token();
    }

  }
  while(!eof()             &&
        token.type_ != '(' &&
        token.type_ != ';' &&
        token.type_ != ',' &&
        token.type_ != '['
       );

  bool is_function= (token.type_ == '(');

  string parmtext;
  string file = token.file_;
  int    line = token.line_;


  if(token.type_ == '(')
  {
    eat_function_parms(&parmtext);
    next_token();
  }
  else
  if(token.type_ == '[')
  {
     // eat until matching ']' -- and eat it too

     int depth = 0;

     while(!eof())
     {
       if(token.type_ == '[')
         ++depth;
       else
       if(token.type_ == ']')
       {
         --depth;
         if(depth == 0)
           break;
       }

       next_token();

     }

     next_token();

     // we should see either ';' or ',' as the token there

     if( token.type_ == '=')
     {
        // consume array initializer body:
        //
        //   int junk[14] = { 1, 2,  }   ;
        //                  ^^^^^^^^^^ 

        next_token();

        if(token.type_ == '{')
        {
            eat_curly_block();

            if(token.type_ == '}')
              next_token();
           
        }

     }


  }


  if(token.type_ == '(')
  {
    // we are dealing with something like a pointer to a function
    // where the following syntax was found:
    //
    //  int (*f)(parms) {}

    tmp.text_ = parmtext;
    tmp.file_ = file;
    tmp.line_ = line;

    eat_function_parms(&parmtext);
    next_token();

  }
  else
  if(token.type_ == ':')
  {
    // ignore the base class initalizers in a constructor's name

    while(!eof() && token.type_ != '{')
      next_token();

  }

  switch(token.type_)
  {
    case CPP_Token::eof:
         return true;

    case ';':

         {
           string variable_type("variable");
           string typename_type("typename");
           string function_type("function");
        
           if(!is_function || log_forward_func_declarations)
            log_symbol( handling_typedefs 
                         ? typename_type 
                         : (is_function 
                            ? function_type
                            : variable_type
                           ),
                       tmp.text_,
                       tmp.file_,
                       tmp.line_
                      );
        
           next_token();
         }
         return false;
        
    case ',':

         {
           static string variable_type("variable");
        
           if(!is_function)
            log_symbol(variable_type, tmp.text_, tmp.file_, tmp.line_);
        
           next_token();
           return parse_funcvar();
         }
    default:

         {
           static string function_type("function");
        
           outer_scope.setScopeMember(tmp.text_);
           outer_scope.setScopeFileInfo(tmp.file_, tmp.line_);

           log_symbol(function_type, tmp.text_, tmp.file_, tmp.line_);
         }
        
         // handle a goofy g++ variant syntax
        
           if(token.text_ == "return")
           {
             while(!eof() && token.type_ != '{')
               next_token();
           }
        
         // end goofy g++ variant syntax

         while(!eof() && 
               token.type_ != ';' && 
               token.type_ != '{' &&
               token.type_ != ','
              )
         {
           if(token.type_ == '(')
           {
             string trash;
             eat_function_parms(&trash);
             next_token();
           }
           else
             next_token();
         }

         if(token.type_ == '{')
         {
           eat_function_body();

        
           while(token.type_ == ':')
           {
             // presume we are passing a class definition with #if's in it
             // like this:
             //
             //   class X
             //   {
             //     X()
             //     #if 1
             //        : base1() {}
             //     #else
             //        : base2() {}   <-- the parser is now sitting at the ':'
             //     #endif
        
             while(token.type_ != '{')
               next_token();
        
             eat_function_body();
        

        
        
           }
        
         }
         else
             if(token.type_ == ',')
             {
                 next_token();
                 return parse_funcvar();
             }
          else
               next_token();
        
         break;
        
  }


  return false;
}

static bool parse_extern()
//
//  parse extern variables and extern code definitions:
//
//    extern type varname;
//    extern type funcname;
//    extern "c" declaration;
//    extern "c" { declarations ... }
//
{
  next_token();  // eat 'extern'

  if(token.type_ == '"')
  {
     next_token();

     if(token.type_ != '{')
     {
       return parse_declaration();
     }

     next_token();

     while(token.type_ != '}')
     {
       if(parse_declaration())
         return true;
     }

     next_token();

  }
  else
  {
     return parse_declaration();
  }

  return false;
}


static void printInfo()
   // print a commentary on the algorithm.
{

   static char const *info[] =
   {
       "cca.exe:  print McCabe style Cyclomatic Complexity Analysis for C++",
       "",
       "    Copyright 2002, 2010, Lowell Boggs Jr.",
       "",
       "Overview:",
       "",
       "   cca.exe reads C++ source files and produces an cyclomatic",
       "   number for each function defined in that file.  It works on",
       "   both \".cpp\" and \".h\" files.",
       "",
       "   The cyclomatic complexity measure is documented on wikipedia.",
       "   As a general rule, a cyclomatic complexity greater than 10",
       "   indicates that a function will be very difficult to test.",
       "   If possible, such functions are candidates for refactoring.",
       "",
       "   McCabe originally described his metric based on compiler internal",
       "   concepts:  that of basic program blocks.  A basic block is a",
       "   chunk of code with no conditionals statements.  Conditionals",
       "   break up functions into multiple blocks.  Transitions between",
       "   the blocks are key components McCabe's calculation.",
       "",
       "   This program however uses a different strategy for the calculation",
       "   that is based on features of the C++ language itself:  grammar",
       "   and syntax.  By default, this program also relaxes McCabe's",
       "   calculation a bit to account for common programming strategies",
       "   that exaggerate the McCabe metric (at least in the author's",
       "   opinion.  This relaxation can be turned off, see \"-m\".",
       "",
       "   This program does not count basic blocks and their transitions",
       "   but rather it counts conditionals.  Every function begins with",
       "   an NPATH (number of paths) of 1.  The following statement types",
       "   double the NPATH for the function:",
       "",
       "       if",
       "       while",
       "       for",
       "       do-while",
       "",
       "   The base-2 logarithm of the path count is printed as the",
       "   cyclomatic complexity for the function.",
       "",
       "   Switch statements don't double the complexity, but rather they",
       "   multiply it by the count of case/default clauses.",
       "",
       "   Nested statements are accounted for in the metric.  When dealing",
       "   with if-statements and switch-statements, the statement itself",
       "   affects the metric, but only the largest nested section affects",
       "   it.  This seems to make sense given that only one clause will",
       "   actually execute.  The section with the largest path count is",
       "   chosen.",
       "",
       "   By default, two extensions to McCabe's analysis are turned on:",
       "",
       "     *  else-if collapsing",
       "     *  return/throw collapsing",
       "",
       "   See options -m, -e, and -r to turn these features off.",
       "",
       "   When else-if combinations occur, only one of the alternatives",
       "   will actually execute.  Thus, having each if-statement in the",
       "   group double the McCabe metric unfairly inflates the path",
       "   count.  If an if-clause or an else-clause has a return statement",
       "   in it, and if that branch is executed, then the rest of the",
       "   statements in the function are short-circuited.  Thus the",
       "   special case of \"if(x) return; else {...} ;\" is treated as",
       "   if the if-statement does not increase the path count.  The",
       "   contents of the else-clause WILL still affect the path count.",
       "",
       "   The '-R returnSynonym' options let you define synonyms for",
       "   the return statement.  Here's an example use:",
       "      -R exit -R THROW_EXCEPTION",
       "   When used, any -R defined symbol will be treated as if it were a",
       "   return statement unless -r or -m is used.",
       "",
       "   try-catch blocks are processed as follows:",
       "     * The try blocks is treated as if were normal code.",
       "     * The catch blocks are treated as alternative sections.",
       "       Only the largest path found in any of the catch blocks",
       "       is kept, so that the total impact on the number of",
       "       execution paths is:",
       "          impact(try) * largest( impact(any catch) )",
       "",
       ""

   };

   for(unsigned i = 0; i < sizeof(info) / sizeof(char const *); ++i)
   {
      cout << info[i] << endl;
   }

}