src/vhdldocgen.h

   1 /******************************************************************************
   2  *
   3  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   4  *
   5  * Permission to use, copy, modify, and distribute this software and its
   6  * documentation under the terms of the GNU General Public License is hereby
   7  * granted. No representations are made about the suitability of this software
   8  * for any purpose. It is provided "as is" without express or implied warranty.
   9  * See the GNU General Public License for more details.
  10  *
  11  * Documents produced by Doxygen are derivative works derived from the
  12  * input used in their production; they are not affected by this license.
  13  *
  14  */
  15
  16 #ifndef VHDLDOCGEN_H
  17 #define VHDLDOCGEN_H
  18
  19 /**
  20  * This class implements functions for parsing and generating
  21  * vhdl documents
  22  */
  23
  24 #include <qdict.h>
  25 #include <qcstring.h>
  26 #include "layout.h"
  27 #include "arguments.h"
  28 #include "entry.h"
  29
  30 class Entry;
  31 class ClassDef;
  32 class MemberList;
  33 class MemberDef;
  34 class FTextStream;
  35 class OutputList;
  36 class Definition;
  37 class GroupDef;
  38 class FileDef;
  39 class NamespaceDef;
  40 struct Argument;
  41
  42 /** Class for generating documentation specific for VHDL */
  43 class VhdlDocGen
  44 {
  45   public:
  46
  47     enum VhdlClasses       // Overlays: Protection
  48     {
  49       ENTITYCLASS,         // Overlays: Public
  50       PACKBODYCLASS,       // Overlays: Protected
  51       ARCHITECTURECLASS,   // Overlays: Private
  52       PACKAGECLASS         // Overlays: Package
  53     };
  54
  55     enum VhdlKeyWords
  56     {
  57       LIBRARY=1,
  58       ENTITY,
  59       PACKAGE_BODY,
  60       ARCHITECTURE,
  61       PACKAGE,
  62       ATTRIBUTE,
  63       SIGNAL,
  64       COMPONENT,
  65       CONSTANT,
  66       TYPE,
  67       SUBTYPE,
  68       FUNCTION,
  69       RECORD,
  70       PROCEDURE,
  71       USE,
  72       PROCESS,
  73       PORT,
  74       UNITS,
  75       GENERIC,
  76       INSTANTIATION,
  77       GROUP,
  78       VFILE,
  79       SHAREDVARIABLE,
  80       CONFIG,
  81       ALIAS,
  82       MISCELLANEOUS,
  83       UCF_CONST
  84     };
  85
  86     VhdlDocGen();
  87     virtual ~VhdlDocGen();
  88     static void init();
  89     static QCString convertFileNameToClassName(QCString name);
  90     // --- used by vhdlscanner.l -----------
  91
  92     static bool isSubClass(ClassDef* cd,ClassDef *scd, bool followInstances,int level);
  93
  94     static QCString getIndexWord(const char* ,int index);
  95     static bool     deleteCharRev(QCString &s,char c);
  96     static void     deleteAllChars(QCString &s,char c);
  97     static void     parseFuncProto(const char* text,
  98                                    QList<Argument>& ,
  99                                    QCString& name,
 100                                    QCString& ret,
 101                                    bool doc=false);
 102     // -----------------------------------
 103
 104     static void computeVhdlComponentRelations();
 105
 106     static QCString* findKeyWord(const QCString& word);
 107
 108     static ClassDef* getPackageName(const QCString& name);
 109     static MemberDef* findMember(const QCString& className,
 110                                  const QCString& memName);
 111     static void findAllPackages(ClassDef*);
 112     static MemberDef* findMemberDef(ClassDef* cd,
 113                                 const QCString& key,
 114                                 MemberListType type);
 115     static ClassDef *getClass(const char *name);
 116     static MemberDef* findFunction(const QList<Argument> &ql,
 117                                    const QCString& name,
 118                                    const QCString& package, bool type);
 119     static QCString getClassTitle(const ClassDef*);
 120     static void writeInlineClassLink(const ClassDef*,
 121                                      OutputList &ol);
 122     static void writeTagFile(MemberDef *mdef,FTextStream &tagFile);
 123
 124     static bool isConstraint(const MemberDef *mdef);
 125     static bool isConfig(const MemberDef *mdef);
 126     static bool isAlias(const MemberDef *mdef);
 127     static bool isLibrary(const MemberDef *mdef);
 128     static bool isGeneric(const MemberDef *mdef);
 129     static bool isPort(const MemberDef *mdef);
 130     static bool isComponent(const MemberDef *mdef);
 131     static bool isPackage(const MemberDef *mdef);
 132     static bool isEntity(const MemberDef *mdef);
 133     static bool isConstant(const MemberDef *mdef);
 134     static bool isVType(const MemberDef *mdef);
 135     static bool isSubType(const MemberDef *mdef);
 136     static bool isVhdlFunction(const MemberDef *mdef);
 137     static bool isProcess(const MemberDef *mdef);
 138     static bool isSignal(const MemberDef *mdef);
 139     static bool isAttribute(const MemberDef *mdef);
 140     static bool isSignals(const MemberDef *mdef);
 141     static bool isProcedure(const MemberDef *mdef);
 142     static bool isRecord(const MemberDef *mdef);
 143     static bool isArchitecture(const MemberDef *mdef);
 144     static bool isUnit(const MemberDef *mdef);
 145     static bool isPackageBody(const MemberDef *mdef);
 146     static bool isVariable(const MemberDef *mdef);
 147     static bool isFile(const MemberDef *mdef);
 148     static bool isGroup(const MemberDef *mdef);
 149     static bool isCompInst(const MemberDef *mdef);
 150     static bool isMisc(const MemberDef *mdef);
 151
 152     //-----------------------------------------------------
 153     // translatable items
 154
 155     static QCString trTypeString(uint64 type);
 156     static QCString trVhdlType(uint64 type,bool sing=true);
 157
 158     // trClassHierarchy.
 159     static QCString trDesignUnitHierarchy();
 160
 161     // trCompoundList
 162     static QCString trDesignUnitList();
 163
 164     // trCompoundMembers.
 165     static QCString trDesignUnitMembers();
 166
 167     // trCompoundListDescription
 168     static QCString trDesignUnitListDescription();
 169
 170     // trCompounds
 171     static QCString trDesignUnits();
 172
 173     // trCompoundIndex
 174     static QCString trDesignUnitIndex();
 175
 176     // trFunctions
 177     static QCString trFunctionAndProc();
 178
 179     //-----------------------------------------------------
 180
 181     static void prepareComment(QCString&);
 182     static void formatString(const QCString&,OutputList& ol,const MemberDef*);
 183
 184     static void writeFormatString(const QCString&,OutputList& ol,const MemberDef*);
 185     static void writeFunctionProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 186     static void writeProcessProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 187     static void writeProcedureProto(OutputList& ol, const ArgumentList *al,const MemberDef*);
 188     static bool writeFuncProcDocu(const MemberDef *mdef, OutputList& ol,const ArgumentList* al,bool type=false);
 189     static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList *al);
 190
 191     static bool writeVHDLTypeDocumentation(const MemberDef* mdef, const Definition* d, OutputList &ol);
 192
 193     static void writeVhdlDeclarations(MemberList*,OutputList&,GroupDef*,ClassDef*,FileDef*,NamespaceDef*);
 194
 195     static void writeVHDLDeclaration(MemberDef* mdef,OutputList &ol,
 196         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 197         bool inGroup);
 198
 199     static void writePlainVHDLDeclarations(MemberList* ml,OutputList &ol,
 200         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,int specifier);
 201
 202     static void writeVHDLDeclarations(MemberList* ml,OutputList &ol,
 203         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 204         const char *title,const char *subtitle,bool showEnumValues,int type);
 205
 206     static bool writeClassType(ClassDef *&,OutputList &ol ,QCString & cname);
 207
 208     static QCString convertArgumentListToString(const ArgumentList* al,bool f);
 209     static QCString getProcessNumber();
 210     static QCString getRecordNumber();
 211
 212     static QCString getClassName(const ClassDef*);
 213     static bool isNumber(const QCString& s);
 214     static QCString getProtectionName(int prot);
 215
 216     static void parseUCF(const char*  input,Entry* entity,QCString f,bool vendor);
 217     static bool findConstraintFile( LayoutNavEntry *lne);
 218
 219     static ClassDef*  findArchitecture(const ClassDef *cd);
 220     static ClassDef*  findArchitecture(QCString identifier, QCString entity_name);
 221
 222
 223     static void writeSource(MemberDef *mdef,OutputList& ol,QCString & cname);
 224     static void writeAlphbeticalClass(OutputList& ol,const ClassDef* cd,const QCString &);
 225
 226     static QCString  parseForConfig(QCString & entity,QCString & arch);
 227     static QCString  parseForBinding(QCString & entity,QCString & arch);
 228     static void addBaseClass(ClassDef* cd,ClassDef *ent);
 229     static ClassDef* findVhdlClass(const char *className );
 230
 231     static void writeOverview(OutputList &ol);
 232     static void writeOverview();
 233
 234  // flowcharts
 235     static void createFlowChart(const MemberDef*);
 236     //static void addFlowImage(const FTextStream &,const QCString &);
 237
 238     static void setFlowMember( const MemberDef *flowMember);
 239     static const MemberDef *getFlowMember();
 240
 241     static  bool isVhdlClass (const Entry *cu)
 242     {
 243       return cu->spec==VhdlDocGen::ENTITY       ||
 244              cu->spec==VhdlDocGen::PACKAGE      ||
 245              cu->spec==VhdlDocGen::ARCHITECTURE ||
 246              cu->spec==VhdlDocGen::PACKAGE_BODY;
 247     }
 248
 249   static void resetCodeVhdlParserState();
 250
 251   private:
 252     static void findAllArchitectures(QList<QCString>& ql,const ClassDef *cd);
 253     static bool compareArgList(ArgumentList*,ArgumentList*);
 254     static void writeVhdlLink(const ClassDef* cdd ,OutputList& ol,QCString& type,QCString& name,QCString& beh);
 255     static void writeStringLink(const MemberDef *mdef,QCString mem,OutputList& ol);
 256     static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs);
 257     static void  writeRecorUnit(QCString & largs,OutputList& ol ,const MemberDef *mdef);
 258 };
 259
 260 //-------------------------------------------------------------------------------------------------------------------
 261 //-------------- VHDL Flowcharts -------------------------------------------------------------------------------
 262 //-------------------------------------------------------------------------------------------------------------------
 263
 264
 265 //#define DEBUGFLOW
 266
 267 class FlowChart
 268 {
 269   public:
 270     enum nodeTypes {
 271       IF_NO        = 1<<1,
 272       ELSIF_NO     = 1<<2,
 273       ELSE_NO      = 1<<3,
 274       CASE_NO      = 1<<4,
 275       WHEN_NO      = 1<<5,
 276       EXIT_NO      = 1<<6,
 277       END_NO       = 1<<7,
 278       TEXT_NO      = 1<<8,
 279       START_NO     = 1<<9,
 280       ENDIF_NO     = 1<<10,
 281       FOR_NO       = 1<<11,
 282       WHILE_NO     = 1<<12,
 283       END_LOOP     = 1<<13,
 284       END_CASE     = 1<<14,
 285       VARIABLE_NO  = 1<<15,
 286       RETURN_NO    = 1<<16,
 287       LOOP_NO      = 1<<17,
 288       NEXT_NO      = 1<<18,
 289       EMPTY_NO     = 1<<19,
 290       COMMENT_NO   = 1<<20,
 291       BEGIN_NO     = 1<<21
 292     };
 293
 294     //---------- create svg -------------------------------------------------------------
 295     static void createSVG();
 296     static void startDot(FTextStream &t);
 297     static void endDot(FTextStream &t);
 298     static void codify(FTextStream &t,const char *str);
 299     static void writeShape(FTextStream &t,const FlowChart* fl);
 300     static void writeEdge(FTextStream &t,int fl_from,int fl_to,int i,bool bFrom=FALSE,bool bTo=FALSE);
 301     static void writeEdge(FTextStream &t,const FlowChart* fl_from,const FlowChart* fl_to,int i);
 302     static void writeFlowLinks(FTextStream &t);
 303
 304     static QCString getNodeName(int n);
 305     static void colTextNodes();
 306
 307     static int getNextTextLink(const FlowChart* fl,uint index);
 308     static int getNextIfLink(const FlowChart*,uint);
 309     static int getNextNode(int,int);
 310     static int findNode(int index,int stamp,int type);
 311     static int findNode(int index,int type);
 312     static int findNextLoop(int j,int stamp);
 313     static int findPrevLoop(int j,int stamp,bool endif=FALSE);
 314     static int findLabel(int j,QCString &);
 315     static void delFlowList();
 316     static const char* getNodeType(int c);
 317
 318     static void addFlowChart(int type,const char* text,const char* exp,const char * label=0);
 319     static void moveToPrevLevel();
 320     static int getTimeStamp();
 321     static void writeFlowChart();
 322     static void alignFuncProc(QCString & q,const ArgumentList*  al,bool isFunc);
 323     static QCString convertNameToFileName();
 324     static void printNode(const FlowChart* n);
 325     static void printFlowTree();
 326     static void buildCommentNodes(FTextStream &t);
 327     static void alignCommentNode(FTextStream &t,QCString com);
 328
 329     static void  printUmlTree();
 330     static QCString printPlantUmlNode(const FlowChart *flo,bool,bool);
 331
 332     static QList<FlowChart> flowList;
 333
 334     FlowChart(int typ,const char*  t,const char* ex,const char* label=0);
 335     ~FlowChart();
 336
 337 private:
 338     int id;
 339     int stamp;
 340     int type;
 341
 342     int line;
 343
 344     QCString label;
 345     QCString text;
 346     QCString exp;
 347 };
 348
 349 #endif