utils/ifacecheck/src/ifacecheck.cpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ifacecheck.cpp
   3 // Purpose:     Interface headers <=> real headers coherence checker
   4 // Author:      Francesco Montorsi
   5 // Created:     2008/03/17
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2008 Francesco Montorsi
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 // For compilers that support precompilation, includes "wx/wx.h".
  12 #include "wx/wxprec.h"
  13
  14 #ifdef __BORLANDC__
  15     #pragma hdrstop
  16 #endif
  17
  18 // for all others, include the necessary headers
  19 #ifndef WX_PRECOMP
  20     #include "wx/app.h"
  21 #endif
  22
  23 #include "wx/cmdline.h"
  24 #include "wx/textfile.h"
  25 #include "wx/filename.h"
  26 #include "wx/stopwatch.h"       // for wxGetLocalTime
  27 #include "xmlparser.h"
  28
  29 // global verbosity flag
  30 bool g_verbose = false;
  31
  32
  33
  34 // ----------------------------------------------------------------------------
  35 // IfaceCheckApp
  36 // ----------------------------------------------------------------------------
  37
  38 #define API_DUMP_FILE           "dump.api.txt"
  39 #define INTERFACE_DUMP_FILE     "dump.interface.txt"
  40
  41 #define PROCESS_ONLY_SWITCH     "p"
  42 #define MODIFY_SWITCH           "m"
  43 #define DUMP_SWITCH             "d"
  44 #define HELP_SWITCH             "h"
  45 #define VERBOSE_SWITCH          "v"
  46
  47 static const wxCmdLineEntryDesc g_cmdLineDesc[] =
  48 {
  49     { wxCMD_LINE_OPTION, PROCESS_ONLY_SWITCH, "process-only",
  50         "processes only header files matching the given wildcard",
  51         wxCMD_LINE_VAL_STRING, wxCMD_LINE_NEEDS_SEPARATOR },
  52     { wxCMD_LINE_SWITCH, MODIFY_SWITCH, "modify",
  53         "modify the interface headers to match the real ones" },
  54     { wxCMD_LINE_SWITCH, DUMP_SWITCH, "dump",
  55         "dump both interface and API to plain text dump.*.txt files" },
  56     { wxCMD_LINE_SWITCH, HELP_SWITCH, "help",
  57         "show help message", wxCMD_LINE_VAL_NONE, wxCMD_LINE_OPTION_HELP },
  58     { wxCMD_LINE_SWITCH, VERBOSE_SWITCH, "verbose",
  59         "be verbose" },
  60     { wxCMD_LINE_PARAM,  NULL, NULL,
  61         "gccXML", wxCMD_LINE_VAL_STRING, wxCMD_LINE_OPTION_MANDATORY },
  62     { wxCMD_LINE_PARAM,  NULL, NULL,
  63         "doxygenXML", wxCMD_LINE_VAL_STRING, wxCMD_LINE_OPTION_MANDATORY },
  64     wxCMD_LINE_DESC_END
  65 };
  66
  67 class IfaceCheckApp : public wxAppConsole
  68 {
  69 public:
  70     // don't use builtin cmd line parsing:
  71     virtual bool OnInit() { m_modify=false; return true; }
  72     virtual int OnRun();
  73
  74     bool Compare();
  75     int CompareClasses(const wxClass* iface, const wxClassPtrArray& api);
  76     void FixMethod(const wxString& header, const wxMethod* iface, const wxMethod* api);
  77
  78     void ShowProgress();
  79     void PrintStatistics(long secs);
  80
  81     bool IsToProcess(const wxString& headername) const
  82     {
  83         if (m_strToMatch.IsEmpty())
  84             return true;
  85         return wxMatchWild(m_strToMatch, headername, false);
  86     }
  87
  88 protected:
  89     wxXmlGccInterface m_api;                  // "real" headers API
  90     wxXmlDoxygenInterface m_interface;        // doxygen-commented headers API
  91
  92     // was the MODIFY_SWITCH passed?
  93     bool m_modify;
  94
  95     // if non-empty, then PROCESS_ONLY_SWITCH was passed and this is the
  96     // wildcard expression to match
  97     wxString m_strToMatch;
  98 };
  99
 100 IMPLEMENT_APP_CONSOLE(IfaceCheckApp)
 101
 102 int IfaceCheckApp::OnRun()
 103 {
 104     long startTime = wxGetLocalTime();      // for timing purpose
 105
 106     // parse the command line...
 107     wxCmdLineParser parser(g_cmdLineDesc, argc, argv);
 108     bool ok = true;
 109     switch (parser.Parse())
 110     {
 111         case -1:
 112             // HELP_SWITCH was passed
 113             return 0;
 114
 115         case 0:
 116             if (parser.Found(VERBOSE_SWITCH))
 117                 g_verbose = true;
 118
 119             if (!m_api.Parse(parser.GetParam(0)) ||
 120                 !m_interface.Parse(parser.GetParam(1)))
 121                 return 1;
 122
 123             if (parser.Found(DUMP_SWITCH))
 124             {
 125                 LogMessage("Dumping real API to '%s'...", API_DUMP_FILE);
 126                 m_api.Dump(API_DUMP_FILE);
 127
 128                 LogMessage("Dumping interface API to '%s'...", INTERFACE_DUMP_FILE);
 129                 m_interface.Dump(INTERFACE_DUMP_FILE);
 130             }
 131             else
 132             {
 133                 if (parser.Found(MODIFY_SWITCH))
 134                     m_modify = true;
 135
 136                 if (parser.Found(PROCESS_ONLY_SWITCH, &m_strToMatch))
 137                 {
 138                     size_t len = m_strToMatch.Len();
 139                     if (m_strToMatch.StartsWith("\"") &&
 140                         m_strToMatch.EndsWith("\"") &&
 141                         len > 2)
 142                         m_strToMatch = m_strToMatch.Mid(1, len-2);
 143                 }
 144
 145                 ok = Compare();
 146             }
 147
 148             PrintStatistics(wxGetLocalTime() - startTime);
 149             return ok ? 0 : 1;
 150     }
 151
 152     return 1;
 153 }
 154
 155 void IfaceCheckApp::ShowProgress()
 156 {
 157     wxPrint(".");
 158     //fflush(stdout);
 159 }
 160
 161 bool IfaceCheckApp::Compare()
 162 {
 163     const wxClassArray& interface = m_interface.GetClasses();
 164     const wxClass* c;
 165     wxClassPtrArray api;
 166     int mcount = 0, ccount = 0;
 167
 168     LogMessage("Comparing the interface API to the real API (%d classes to compare)...",
 169                interface.GetCount());
 170
 171     if (!m_strToMatch.IsEmpty())
 172         LogMessage("Processing only header files matching '%s' expression.", m_strToMatch);
 173
 174     for (unsigned int i=0; i<interface.GetCount(); i++)
 175     {
 176         // shorten the name of the header so the log file is more readable
 177         // and also for calling IsToProcess() against it
 178         wxString header = wxFileName(interface[i].GetHeader()).GetFullName();
 179
 180         if (!IsToProcess(header))
 181             continue;       // skip this one
 182
 183         wxString cname = interface[i].GetName();
 184
 185         api.Empty();
 186
 187         // search in the real headers for i-th interface class
 188         // for both class cname and cnameBase as in wxWidgets world, most often
 189         // class cname is platform-specific while the real public interface of
 190         // that class is part of the cnameBase class.
 191         c = m_api.FindClass(cname);
 192         if (c) api.Add(c);
 193         c = m_api.FindClass(cname + "Base");
 194         if (c) api.Add(c);
 195
 196         if (api.GetCount()>0) {
 197
 198             // there is a class with exactly the same name!
 199             mcount += CompareClasses(&interface[i], api);
 200
 201         } else {
 202
 203             LogMessage("%s: couldn't find the real interface for the '%s' class",
 204                        header, cname);
 205             ccount++;
 206         }
 207     }
 208
 209     LogMessage("%d methods (%.1f%%) of the interface headers do not exist in the real headers",
 210                mcount, (float)(100.0 * mcount/m_interface.GetMethodCount()));
 211     LogMessage("%d classes (%.1f%%) of the interface headers do not exist in the real headers",
 212                ccount, (float)(100.0 * ccount/m_interface.GetClassesCount()));
 213
 214     return true;
 215 }
 216
 217 int IfaceCheckApp::CompareClasses(const wxClass* iface, const wxClassPtrArray& api)
 218 {
 219     wxString searchedclasses;
 220     const wxMethod *real;
 221     int count = 0;
 222
 223     wxASSERT(iface && api.GetCount()>0);
 224
 225     // build a string with the names of the API classes compared to iface
 226     for (unsigned int j=0; j<api.GetCount(); j++)
 227         searchedclasses += "/" + api[j]->GetName();
 228     searchedclasses.Remove(0, 1);
 229
 230     // shorten the name of the header so the log file is more readable
 231     wxString header = wxFileName(iface->GetHeader()).GetFullName();
 232
 233     for (unsigned int i=0; i<iface->GetMethodCount(); i++)
 234     {
 235         const wxMethod& m = iface->GetMethod(i);
 236         int matches = 0;
 237
 238         // search in the methods of the api classes provided
 239         for (unsigned int j=0; j<api.GetCount(); j++)
 240         {
 241             real = api[j]->FindMethod(m);
 242             if (real)
 243                 matches++;                // there is a real matching prototype! It's ok!
 244         }
 245
 246         if (matches == 0)
 247         {
 248             wxMethodPtrArray overloads;
 249
 250             // try searching for a method with the same name but with
 251             // different return type / arguments / qualifiers
 252             for (unsigned int j=0; j<api.GetCount(); j++)
 253             {
 254                 wxMethodPtrArray results = api[j]->FindMethodNamed(m.GetName());
 255
 256                 // append "results" array to "overloads"
 257                 WX_APPEND_ARRAY(overloads, results);
 258             }
 259
 260             if (overloads.GetCount()==0)
 261             {
 262                 /*
 263                     TODO: sometimes the interface headers re-document a method
 264                           inherited from a base class even if the real header does
 265                           not actually re-implement it.
 266                           To avoid false positives, we'd need to search in the base classes
 267                           of api[] classes and search for a matching method.
 268                 */
 269                 LogMessage("%s: real '%s' class has no method '%s'",
 270                             header, searchedclasses, m.GetAsString());
 271                 // we've found no overloads
 272             }
 273             else
 274             {
 275                 // first, output a warning
 276                 wxString warning = header;
 277                 if (overloads.GetCount()>1)
 278                     warning += wxString::Format(": in the real headers there are %d overloads of '%s' for "
 279                                                 "'%s' all with different signatures:\n",
 280                                                 overloads.GetCount(), m.GetName(), searchedclasses);
 281                 else
 282                     warning += wxString::Format(": in the real headers there is a method '%s' for '%s'"
 283                                                 " but has different signature:\n",
 284                                                 m.GetName(), searchedclasses);
 285
 286                 warning += "\tdoxy header: " + m.GetAsString();
 287                 for (unsigned int j=0; j<overloads.GetCount(); j++)
 288                     warning += "\n\treal header: " + overloads[j]->GetAsString();
 289
 290                 wxPrint(warning + "\n");
 291                 count++;
 292
 293                 if (overloads.GetCount()>1)
 294                 {
 295                     // TODO: decide which of these overloads is the most "similar" to m
 296                     //       and eventually modify it
 297                     if (m_modify)
 298                         wxPrint("\tmanual fix is required\n");
 299                 }
 300                 else
 301                 {
 302                     wxASSERT(overloads.GetCount() == 1);
 303
 304                     if (m_modify)
 305                     {
 306                         wxPrint("\tfixing it...\n");
 307
 308                         // try to modify it!
 309                         FixMethod(iface->GetHeader(), &m, overloads[0]);
 310                     }
 311                 }
 312             }
 313
 314             count++;
 315         }
 316     }
 317
 318     return count;
 319 }
 320
 321 void IfaceCheckApp::FixMethod(const wxString& header, const wxMethod* iface, const wxMethod* api)
 322 {
 323     wxASSERT(iface && api);
 324
 325     wxTextFile file;
 326     if (!file.Open(header)) {
 327         LogError("can't open the '%s' header file.", header);
 328         return;
 329     }
 330
 331     // GetLocation() returns the line where the last part of the prototype is placed:
 332     int end = iface->GetLocation()-1;
 333     if (end <= 0 || end >= (int)file.GetLineCount()) {
 334         LogWarning("invalid location info for method '%s': %d.",
 335                    iface->GetAsString(), iface->GetLocation());
 336         return;
 337     }
 338
 339     if (!file.GetLine(end).Contains(iface->GetName())) {
 340         LogWarning("invalid location info for method '%s': %d.",
 341                    iface->GetAsString(), iface->GetLocation());
 342         return;
 343     }
 344
 345     // find the start point of this prototype declaration:
 346     int start = end-1;
 347     while (start > 0 &&
 348            !file.GetLine(start).Contains(";") &&
 349            !file.GetLine(start).Contains("*/"))
 350         start--;
 351
 352     if (start <= 0)
 353     {
 354         LogError("can't find the beginning of the declaration of '%s' method in '%s' header",
 355                     iface->GetAsString(), header);
 356         return;
 357     }
 358
 359     // start-th line contains either the declaration of another prototype
 360     // or the closing tag */ of a doxygen comment; start one line below
 361     start++;
 362
 363     // remove the old prototype
 364     for (int i=start; i<=end; i++)
 365         file.RemoveLine(start);     // remove (end-start)-nth times the start-th line
 366
 367 #define INDENTATION_STR  wxString("    ")
 368
 369     // if possible, add also the @deprecated tag in the doxygen comment
 370     if (file.GetLine(start-1).Contains("*/") && api->IsDeprecated())
 371     {
 372         file.RemoveLine(start-1);
 373         file.InsertLine(INDENTATION_STR + INDENTATION_STR +
 374                         "@deprecated @todo provide deprecation description", start-1);
 375         file.InsertLine(INDENTATION_STR + "*/", start++);
 376     }
 377
 378     wxMethod tmp(*api);
 379
 380     // discard API argument names and replace them with those parsed from doxygen XML:
 381     const wxArgumentTypeArray& doxygenargs = iface->GetArgumentTypes();
 382     const wxArgumentTypeArray& realargs = api->GetArgumentTypes();
 383     if (realargs.GetCount() == doxygenargs.GetCount())
 384     {
 385         for (unsigned int j=0; j<doxygenargs.GetCount(); j++)
 386             if (doxygenargs[j]==realargs[j])
 387                 realargs[j].SetArgumentName(doxygenargs[j].GetArgumentName());
 388
 389         tmp.SetArgumentTypes(realargs);
 390     }
 391
 392     // insert the new one
 393     file.InsertLine(INDENTATION_STR + tmp.GetAsString() + ";", start);
 394
 395     // now save the modification
 396     if (!file.Write()) {
 397         LogError("can't save the '%s' header file.", header);
 398         return;
 399     }
 400 }
 401
 402 void IfaceCheckApp::PrintStatistics(long secs)
 403 {
 404     LogMessage("wx real headers contains declaration of %d classes (%d methods)",
 405                m_api.GetClassesCount(), m_api.GetMethodCount());
 406     LogMessage("wx interface headers contains declaration of %d classes (%d methods)",
 407                m_interface.GetClassesCount(), m_interface.GetMethodCount());
 408     LogMessage("total processing took %d seconds.", secs);
 409 }
 410