src/dot.h

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  *
   6  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   7  *
   8  * Permission to use, copy, modify, and distribute this software and its
   9  * documentation under the terms of the GNU General Public License is hereby
  10  * granted. No representations are made about the suitability of this software
  11  * for any purpose. It is provided "as is" without express or implied warranty.
  12  * See the GNU General Public License for more details.
  13  *
  14  * Documents produced by Doxygen are derivative works derived from the
  15  * input used in their production; they are not affected by this license.
  16  *
  17  */
  18
  19 #ifndef _DOT_H
  20 #define _DOT_H
  21
  22 #include <qlist.h>
  23 #include <qdict.h>
  24 #include <qwaitcondition.h>
  25 #include <qmutex.h>
  26 #include <qqueue.h>
  27 #include <qthread.h>
  28 #include "sortdict.h"
  29 #include "classdef.h"
  30
  31 class FileDef;
  32 class FTextStream;
  33 class DotNodeList;
  34 class ClassSDict;
  35 class MemberDef;
  36 class Definition;
  37 class DirDef;
  38 class GroupDef;
  39 class DotGroupCollaboration;
  40 class DotRunnerQueue;
  41
  42 enum GraphOutputFormat    { GOF_BITMAP, GOF_EPS };
  43 enum EmbeddedOutputFormat { EOF_Html, EOF_LaTeX, EOF_Rtf, EOF_DocBook };
  44
  45 // the graphicx LaTeX has a limitation of maximum size of 16384
  46 // To be on the save side we take it a little bit smaller i.e. 150 inch * 72 dpi
  47 // It is anyway hard to view these size of images
  48 #define MAX_LATEX_GRAPH_INCH  150
  49 #define MAX_LATEX_GRAPH_SIZE  (MAX_LATEX_GRAPH_INCH * 72)
  50
  51 /** Attributes of an edge of a dot graph */
  52 struct EdgeInfo
  53 {
  54   enum Colors { Blue=0, Green=1, Red=2, Purple=3, Grey=4, Orange=5, Orange2=6 };
  55   enum Styles { Solid=0, Dashed=1 };
  56   EdgeInfo() : m_color(0), m_style(0), m_labColor(0) {}
  57  ~EdgeInfo() {}
  58   int m_color;
  59   int m_style;
  60   QCString m_label;
  61   QCString m_url;
  62   int m_labColor;
  63 };
  64
  65 /** A node in a dot graph */
  66 class DotNode
  67 {
  68   public:
  69     enum GraphType { Dependency, Inheritance, Collaboration, Hierarchy, CallGraph };
  70     enum TruncState { Unknown, Truncated, Untruncated };
  71     DotNode(int n,const char *lab,const char *tip,const char *url,
  72             bool rootNode=FALSE,ClassDef *cd=0);
  73    ~DotNode();
  74     void addChild(DotNode *n,
  75                   int edgeColor=EdgeInfo::Purple,
  76                   int edgeStyle=EdgeInfo::Solid,
  77                   const char *edgeLab=0,
  78                   const char *edgeURL=0,
  79                   int edgeLabCol=-1
  80                  );
  81     void addParent(DotNode *n);
  82     void deleteNode(DotNodeList &deletedList,SDict<DotNode> *skipNodes=0);
  83     void removeChild(DotNode *n);
  84     void removeParent(DotNode *n);
  85     int findParent( DotNode *n );
  86     void write(FTextStream &t,GraphType gt,GraphOutputFormat f,
  87                bool topDown,bool toChildren,bool backArrows);
  88     int  m_subgraphId;
  89     void clearWriteFlag();
  90     void writeXML(FTextStream &t,bool isClassGraph);
  91     void writeDocbook(FTextStream &t,bool isClassGraph);
  92     void writeDEF(FTextStream &t);
  93     QCString label() const { return m_label; }
  94     int  number() const { return m_number; }
  95     bool isVisible() const { return m_visible; }
  96     TruncState isTruncated() const { return m_truncated; }
  97     int distance() const { return m_distance; }
  98     void renumberNodes(int &number);
  99
 100   private:
 101     void colorConnectedNodes(int curColor);
 102     void writeBox(FTextStream &t,GraphType gt,GraphOutputFormat f,
 103                   bool hasNonReachableChildren);
 104     void writeArrow(FTextStream &t,GraphType gt,GraphOutputFormat f,DotNode *cn,
 105                     EdgeInfo *ei,bool topDown, bool pointBack=TRUE);
 106     void setDistance(int distance);
 107     const DotNode   *findDocNode() const; // only works for acyclic graphs!
 108     void markAsVisible(bool b=TRUE) { m_visible=b; }
 109     void markAsTruncated(bool b=TRUE) { m_truncated=b ? Truncated : Untruncated; }
 110     int              m_number;
 111     QCString         m_label;     //!< label text
 112     QCString         m_tooltip;   //!< node's tooltip
 113     QCString         m_url;       //!< url of the node (format: remote$local)
 114     QList<DotNode>  *m_parents;   //!< list of parent nodes (incoming arrows)
 115     QList<DotNode>  *m_children;  //!< list of child nodes (outgoing arrows)
 116     QList<EdgeInfo> *m_edgeInfo;  //!< edge info for each child
 117     bool             m_deleted;   //!< used to mark a node as deleted
 118     bool             m_written;   //!< used to mark a node as written
 119     bool             m_hasDoc;    //!< used to mark a node as documented
 120     bool             m_isRoot;    //!< indicates if this is a root node
 121     ClassDef *       m_classDef;  //!< class representing this node (can be 0)
 122     bool             m_visible;   //!< is the node visible in the output
 123     TruncState       m_truncated; //!< does the node have non-visible children/parents
 124     int              m_distance;  //!< shortest path to the root node
 125     bool             m_renumbered;//!< indicates if the node has been renumbered (to prevent endless loops)
 126
 127     friend class DotGfxHierarchyTable;
 128     friend class DotClassGraph;
 129     friend class DotInclDepGraph;
 130     friend class DotNodeList;
 131     friend class DotCallGraph;
 132     friend class DotGroupCollaboration;
 133     friend class DotInheritanceGraph;
 134
 135     friend QCString computeMd5Signature(
 136                       DotNode *root, GraphType gt,
 137                       GraphOutputFormat f,
 138                       const QCString &rank,
 139                       bool renderParents,
 140                       bool backArrows,
 141                       const QCString &title,
 142                       QCString &graphStr
 143                      );
 144 };
 145
 146 /** Class representing a list of DotNode objects. */
 147 class DotNodeList : public QList<DotNode>
 148 {
 149   public:
 150     DotNodeList() : QList<DotNode>() {}
 151    ~DotNodeList() {}
 152   private:
 153     int compareValues(const DotNode *n1,const DotNode *n2) const;
 154 };
 155
 156 /** Represents a graphical class hierarchy */
 157 class DotGfxHierarchyTable
 158 {
 159   public:
 160     DotGfxHierarchyTable(const char *prefix="",ClassDef::CompoundType ct=ClassDef::Class);
 161    ~DotGfxHierarchyTable();
 162     void writeGraph(FTextStream &t,const char *path, const char *fileName) const;
 163     void createGraph(DotNode *rootNode,FTextStream &t,const char *path,const char *fileName,int id) const;
 164     const DotNodeList *subGraphs() const { return m_rootSubgraphs; }
 165
 166   private:
 167     void addHierarchy(DotNode *n,ClassDef *cd,bool hide);
 168     void addClassList(ClassSDict *cl);
 169
 170     QCString               m_prefix;
 171     ClassDef::CompoundType m_classType;
 172     QList<DotNode>        *m_rootNodes;
 173     QDict<DotNode>        *m_usedNodes;
 174     int                    m_curNodeNumber;
 175     DotNodeList           *m_rootSubgraphs;
 176 };
 177
 178 /** Representation of a class inheritance or dependency graph */
 179 class DotClassGraph
 180 {
 181   public:
 182     DotClassGraph(ClassDef *cd,DotNode::GraphType t);
 183    ~DotClassGraph();
 184     bool isTrivial() const;
 185     bool isTooBig() const;
 186     QCString writeGraph(FTextStream &t,GraphOutputFormat gf,EmbeddedOutputFormat ef,
 187                     const char *path, const char *fileName, const char *relPath,
 188                     bool TBRank=TRUE,bool imageMap=TRUE,int graphId=-1) const;
 189
 190     void writeXML(FTextStream &t);
 191     void writeDocbook(FTextStream &t);
 192     void writeDEF(FTextStream &t);
 193     static void resetNumbering();
 194
 195   private:
 196     void buildGraph(ClassDef *cd,DotNode *n,bool base,int distance);
 197     bool determineVisibleNodes(DotNode *rootNode,int maxNodes,bool includeParents);
 198     void determineTruncatedNodes(QList<DotNode> &queue,bool includeParents);
 199     void addClass(ClassDef *cd,DotNode *n,int prot,const char *label,
 200                   const char *usedName,const char *templSpec,
 201                   bool base,int distance);
 202
 203     DotNode        *   m_startNode;
 204     QDict<DotNode> *   m_usedNodes;
 205     static int         m_curNodeNumber;
 206     DotNode::GraphType m_graphType;
 207     QCString           m_collabFileName;
 208     QCString           m_inheritFileName;
 209     bool               m_lrRank;
 210 };
 211
 212 /** Representation of an include dependency graph */
 213 class DotInclDepGraph
 214 {
 215   public:
 216     DotInclDepGraph(FileDef *fd,bool inverse);
 217    ~DotInclDepGraph();
 218     QCString writeGraph(FTextStream &t, GraphOutputFormat gf, EmbeddedOutputFormat ef,
 219                     const char *path,const char *fileName,const char *relPath,
 220                     bool writeImageMap=TRUE,int graphId=-1) const;
 221     bool isTrivial() const;
 222     bool isTooBig() const;
 223     QCString diskName() const;
 224     void writeXML(FTextStream &t);
 225     void writeDocbook(FTextStream &t);
 226     static void resetNumbering();
 227
 228   private:
 229     void buildGraph(DotNode *n,FileDef *fd,int distance);
 230     void determineVisibleNodes(QList<DotNode> &queue,int &maxNodes);
 231     void determineTruncatedNodes(QList<DotNode> &queue);
 232
 233     DotNode        *m_startNode;
 234     QDict<DotNode> *m_usedNodes;
 235     static int      m_curNodeNumber;
 236     QCString        m_inclDepFileName;
 237     QCString        m_inclByDepFileName;
 238     bool            m_inverse;
 239 };
 240
 241 /** Representation of an call graph */
 242 class DotCallGraph
 243 {
 244   public:
 245     DotCallGraph(MemberDef *md,bool inverse);
 246    ~DotCallGraph();
 247     QCString writeGraph(FTextStream &t, GraphOutputFormat gf, EmbeddedOutputFormat ef,
 248                         const char *path,const char *fileName,
 249                         const char *relPath,bool writeImageMap=TRUE,
 250                         int graphId=-1) const;
 251     void buildGraph(DotNode *n,MemberDef *md,int distance);
 252     bool isTrivial() const;
 253     bool isTooBig() const;
 254     void determineVisibleNodes(QList<DotNode> &queue, int &maxNodes);
 255     void determineTruncatedNodes(QList<DotNode> &queue);
 256     static void resetNumbering();
 257
 258   private:
 259     DotNode        *m_startNode;
 260     static int             m_curNodeNumber;
 261     QDict<DotNode> *m_usedNodes;
 262     bool            m_inverse;
 263     QCString        m_diskName;
 264     Definition *    m_scope;
 265 };
 266
 267 /** Representation of an directory dependency graph */
 268 class DotDirDeps
 269 {
 270   public:
 271     DotDirDeps(DirDef *dir);
 272    ~DotDirDeps();
 273     bool isTrivial() const;
 274     QCString writeGraph(FTextStream &out,
 275                         GraphOutputFormat gf,
 276                         EmbeddedOutputFormat ef,
 277                         const char *path,
 278                         const char *fileName,
 279                         const char *relPath,
 280                         bool writeImageMap=TRUE,
 281                         int graphId=-1,
 282                         bool linkRelations=TRUE) const;
 283   private:
 284     DirDef *m_dir;
 285 };
 286
 287 /** Representation of a group collaboration graph */
 288 class DotGroupCollaboration
 289 {
 290   public :
 291     enum EdgeType
 292     {  tmember = 0,
 293        tclass,
 294        tnamespace,
 295        tfile,
 296        tpages,
 297        tdir,
 298        thierarchy
 299     };
 300
 301     class Link
 302     {
 303       public:
 304         Link(const QCString lab,const QCString &u) : label(lab), url(u) {}
 305         QCString label;
 306         QCString url;
 307     };
 308
 309     class Edge
 310     {
 311       public :
 312         Edge(DotNode *start,DotNode *end,EdgeType type)
 313           : pNStart(start), pNEnd(end), eType(type)
 314         { links.setAutoDelete(TRUE); }
 315
 316         DotNode* pNStart;
 317         DotNode* pNEnd;
 318         EdgeType eType;
 319
 320         QList<Link> links;
 321         void write( FTextStream &t ) const;
 322     };
 323
 324     DotGroupCollaboration(GroupDef* gd);
 325     ~DotGroupCollaboration();
 326     QCString writeGraph(FTextStream &t, GraphOutputFormat gf,EmbeddedOutputFormat ef,
 327                     const char *path,const char *fileName,const char *relPath,
 328                     bool writeImageMap=TRUE,int graphId=-1) const;
 329     void buildGraph(GroupDef* gd);
 330     bool isTrivial() const;
 331     static void resetNumbering();
 332
 333   private :
 334     void addCollaborationMember( Definition* def, QCString& url, EdgeType eType );
 335     void addMemberList( class MemberList* ml );
 336     void writeGraphHeader(FTextStream &t,const QCString &title) const;
 337     Edge* addEdge( DotNode* _pNStart, DotNode* _pNEnd, EdgeType _eType,
 338                    const QCString& _label, const QCString& _url );
 339
 340     DotNode        *m_rootNode;
 341     static int      m_curNodeNumber;
 342     QDict<DotNode> *m_usedNodes;
 343     QCString        m_diskName;
 344     QList<Edge>     m_edges;
 345 };
 346
 347 /** Minimal constant string class that is thread safe, once initialized. */
 348 class DotConstString
 349 {
 350   public:
 351     DotConstString()                                   { m_str=0; m_pdfstr=0;}
 352    ~DotConstString()                                   { delete[] m_str; delete[] m_pdfstr;}
 353     DotConstString(const QCString &s, const QCString &p = NULL) : m_str(0), m_pdfstr(0)       { set(s); setpdf(p);}
 354     DotConstString(const DotConstString &s) : m_str(0), m_pdfstr(0) { set(s.data()); }
 355     const char *data() const                           { return m_str; }
 356     const char *pdfData() const                        { return m_pdfstr; }
 357     bool isEmpty() const                               { return m_str==0 || m_str[0]=='\0'; }
 358     void set(const QCString &s)
 359     {
 360       delete[] m_str;
 361       m_str=0;
 362       if (!s.isEmpty())
 363       {
 364         m_str=new char[s.length()+1];
 365         qstrcpy(m_str,s.data());
 366       }
 367     }
 368     void setpdf(const QCString &p)
 369     {
 370       delete[] m_pdfstr;
 371       m_pdfstr=0;
 372       if (!p.isEmpty())
 373       {
 374         m_pdfstr=new char[p.length()+1];
 375         qstrcpy(m_pdfstr,p.data());
 376       }
 377     }
 378   private:
 379     DotConstString &operator=(const DotConstString &);
 380     char *m_str;
 381     char *m_pdfstr;
 382 };
 383
 384 /** Helper class to run dot from doxygen.
 385  */
 386 class DotRunner
 387 {
 388   public:
 389     struct CleanupItem
 390     {
 391       DotConstString path;
 392       DotConstString file;
 393     };
 394
 395     /** Creates a runner for a dot \a file. */
 396     DotRunner(const QCString &file,const QCString &fontPath,bool checkResult,
 397         const QCString &imageName = QCString());
 398
 399     /** Adds an additional job to the run.
 400      *  Performing multiple jobs one file can be faster.
 401      */
 402     void addJob(const char *format,const char *output, const char *base = NULL);
 403
 404     void addPostProcessing(const char *cmd,const char *args);
 405
 406     void preventCleanUp() { m_cleanUp = FALSE; }
 407
 408     /** Runs dot for all jobs added. */
 409     bool run();
 410     const CleanupItem &cleanup() const { return m_cleanupItem; }
 411
 412   private:
 413     DotConstString m_dotExe;
 414     bool m_multiTargets;
 415     QList<DotConstString> m_jobs;
 416     DotConstString m_postArgs;
 417     DotConstString m_postCmd;
 418     DotConstString m_file;
 419     DotConstString m_path;
 420     bool m_checkResult;
 421     DotConstString m_imageName;
 422     DotConstString m_imgExt;
 423     bool m_cleanUp;
 424     CleanupItem m_cleanupItem;
 425 };
 426
 427 /** Helper class to insert a set of map file into an output file */
 428 class DotFilePatcher
 429 {
 430   public:
 431     struct Map
 432     {
 433       QCString mapFile;
 434       QCString relPath;
 435       bool     urlOnly;
 436       QCString context;
 437       QCString label;
 438       bool     zoomable;
 439       int      graphId;
 440     };
 441     DotFilePatcher(const char *patchFile);
 442     int addMap(const QCString &mapFile,const QCString &relPath,
 443                bool urlOnly,const QCString &context,const QCString &label);
 444     int addFigure(const QCString &baseName,
 445                   const QCString &figureName,bool heightCheck);
 446     int addSVGConversion(const QCString &relPath,bool urlOnly,
 447                          const QCString &context,bool zoomable,int graphId);
 448     int addSVGObject(const QCString &baseName, const QCString &figureName,
 449                      const QCString &relPath);
 450     bool run();
 451     QCString file() const;
 452
 453   private:
 454     QList<Map> m_maps;
 455     QCString m_patchFile;
 456 };
 457
 458 /** Queue of dot jobs to run. */
 459 class DotRunnerQueue
 460 {
 461   public:
 462     void enqueue(DotRunner *runner);
 463     DotRunner *dequeue();
 464     uint count() const;
 465   private:
 466     QWaitCondition  m_bufferNotEmpty;
 467     QQueue<DotRunner> m_queue;
 468     mutable QMutex  m_mutex;
 469 };
 470
 471 /** Worker thread to execute a dot run */
 472 class DotWorkerThread : public QThread
 473 {
 474   public:
 475     DotWorkerThread(DotRunnerQueue *queue);
 476     void run();
 477     void cleanup();
 478   private:
 479     DotRunnerQueue *m_queue;
 480     QList<DotRunner::CleanupItem> m_cleanupItems;
 481 };
 482
 483 /** Singleton that manages dot relation actions */
 484 class DotManager
 485 {
 486   public:
 487     static DotManager *instance();
 488     void addRun(DotRunner *run);
 489     int  addMap(const QCString &file,const QCString &mapFile,
 490                 const QCString &relPath,bool urlOnly,
 491                 const QCString &context,const QCString &label);
 492     int addFigure(const QCString &file,const QCString &baseName,
 493                   const QCString &figureName,bool heightCheck);
 494     int addSVGConversion(const QCString &file,const QCString &relPath,
 495                bool urlOnly,const QCString &context,bool zoomable,int graphId);
 496     int addSVGObject(const QCString &file,const QCString &baseName,
 497                      const QCString &figureNAme,const QCString &relPath);
 498     bool run();
 499
 500   private:
 501     DotManager();
 502     virtual ~DotManager();
 503     QList<DotRunner>       m_dotRuns;
 504     SDict<DotFilePatcher> m_dotMaps;
 505     static DotManager     *m_theInstance;
 506     DotRunnerQueue        *m_queue;
 507     QList<DotWorkerThread> m_workers;
 508 };
 509
 510
 511 /** Generated a graphs legend page */
 512 void generateGraphLegend(const char *path);
 513
 514 void writeDotGraphFromFile(const char *inFile,const char *outDir,
 515                            const char *outFile,GraphOutputFormat format);
 516 void writeDotImageMapFromFile(FTextStream &t,
 517                               const QCString& inFile, const QCString& outDir,
 518                               const QCString& relPath,const QCString& baseName,
 519                               const QCString& context,int graphId=-1);
 520
 521 void resetDotNodeNumbering();
 522
 523 #endif