src/vhdldocgen.h

   1 /******************************************************************************
   2  *
   3  * Copyright (C) 1997-2013 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
 123     static bool isConstraint(const MemberDef *mdef);
 124     static bool isConfig(const MemberDef *mdef);
 125     static bool isAlias(const MemberDef *mdef);
 126     static bool isLibrary(const MemberDef *mdef);
 127     static bool isGeneric(const MemberDef *mdef);
 128     static bool isPort(const MemberDef *mdef);
 129     static bool isComponent(const MemberDef *mdef);
 130     static bool isPackage(const MemberDef *mdef);
 131     static bool isEntity(const MemberDef *mdef);
 132     static bool isConstant(const MemberDef *mdef);
 133     static bool isVType(const MemberDef *mdef);
 134     static bool isSubType(const MemberDef *mdef);
 135     static bool isVhdlFunction(const MemberDef *mdef);
 136     static bool isProcess(const MemberDef *mdef);
 137     static bool isSignal(const MemberDef *mdef);
 138     static bool isAttribute(const MemberDef *mdef);
 139     static bool isSignals(const MemberDef *mdef);
 140     static bool isProcedure(const MemberDef *mdef);
 141     static bool isRecord(const MemberDef *mdef);
 142     static bool isArchitecture(const MemberDef *mdef);
 143     static bool isUnit(const MemberDef *mdef);
 144     static bool isPackageBody(const MemberDef *mdef);
 145     static bool isVariable(const MemberDef *mdef);
 146     static bool isFile(const MemberDef *mdef);
 147     static bool isGroup(const MemberDef *mdef);
 148     static bool isCompInst(const MemberDef *mdef);
 149     static bool isMisc(const MemberDef *mdef);
 150
 151     //-----------------------------------------------------
 152     // translatable items
 153
 154     static QCString trTypeString(uint64 type);
 155     static QCString trVhdlType(uint64 type,bool sing=true);
 156
 157     // trClassHierarchy.
 158     static QCString trDesignUnitHierarchy();
 159
 160     // trCompoundList
 161     static QCString trDesignUnitList();
 162
 163     // trCompoundMembers.
 164     static QCString trDesignUnitMembers();
 165
 166     // trCompoundListDescription
 167     static QCString trDesignUnitListDescription();
 168
 169     // trCompounds
 170     static QCString trDesignUnits();
 171
 172     // trCompoundIndex
 173     static QCString trDesignUnitIndex();
 174
 175     // trFunctions
 176     static QCString trFunctionAndProc();
 177
 178     //-----------------------------------------------------
 179
 180     static void prepareComment(QCString&);
 181     static void formatString(const QCString&,OutputList& ol,const MemberDef*);
 182
 183     static void writeFormatString(const QCString&,OutputList& ol,const MemberDef*);
 184     static void writeFunctionProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 185     static void writeProcessProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
 186     static void writeProcedureProto(OutputList& ol, const ArgumentList *al,const MemberDef*);
 187     static bool writeFuncProcDocu(const MemberDef *mdef, OutputList& ol,const ArgumentList* al,bool type=false);
 188     static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList *al);
 189
 190     static bool writeVHDLTypeDocumentation(const MemberDef* mdef, const Definition* d, OutputList &ol);
 191
 192     static void writeVhdlDeclarations(MemberList*,OutputList&,GroupDef*,ClassDef*,FileDef*,NamespaceDef*);
 193
 194     static void writeVHDLDeclaration(MemberDef* mdef,OutputList &ol,
 195         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 196         bool inGroup);
 197
 198     static void writePlainVHDLDeclarations(MemberList* ml,OutputList &ol,
 199         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,int specifier);
 200
 201     static void writeVHDLDeclarations(MemberList* ml,OutputList &ol,
 202         ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
 203         const char *title,const char *subtitle,bool showEnumValues,int type);
 204
 205     static bool writeClassType(ClassDef *&,OutputList &ol ,QCString & cname);
 206
 207     static QCString convertArgumentListToString(const ArgumentList* al,bool f);
 208     static QCString getProcessNumber();
 209     static QCString getRecordNumber();
 210
 211     static QCString getClassName(const ClassDef*);
 212     static bool isNumber(const QCString& s);
 213     static QCString getProtectionName(int prot);
 214
 215     static void parseUCF(const char*  input,Entry* entity,QCString f,bool vendor);
 216     static bool findConstraintFile( LayoutNavEntry *lne);
 217
 218     static ClassDef*  findArchitecture(const ClassDef *cd);
 219     static ClassDef*  findArchitecture(QCString identifier, QCString entity_name);
 220
 221
 222     static void writeSource(MemberDef *mdef,OutputList& ol,QCString & cname);
 223     static void writeAlphbeticalClass(OutputList& ol,const ClassDef* cd,const QCString &);
 224
 225     static QCString  parseForConfig(QCString & entity,QCString & arch);
 226     static QCString  parseForBinding(QCString & entity,QCString & arch);
 227     static void addBaseClass(ClassDef* cd,ClassDef *ent);
 228     static ClassDef* findVhdlClass(const char *className );
 229
 230     static void writeOverview(OutputList &ol);
 231     static void writeOverview();
 232
 233  // flowcharts
 234     static void createFlowChart(const MemberDef*);
 235     //static void addFlowImage(const FTextStream &,const QCString &);
 236
 237     static void setFlowMember( const MemberDef *flowMember);
 238     static const MemberDef *getFlowMember();
 239
 240     static  bool isVhdlClass (const Entry *cu)
 241     {
 242       return cu->spec==VhdlDocGen::ENTITY       ||
 243              cu->spec==VhdlDocGen::PACKAGE      ||
 244              cu->spec==VhdlDocGen::ARCHITECTURE ||
 245              cu->spec==VhdlDocGen::PACKAGE_BODY;
 246     }
 247
 248   static void resetCodeVhdlParserState();
 249
 250   private:
 251     static void findAllArchitectures(QList<QCString>& ql,const ClassDef *cd);
 252     static bool compareArgList(ArgumentList*,ArgumentList*);
 253     static void writeVhdlLink(const ClassDef* cdd ,OutputList& ol,QCString& type,QCString& name,QCString& beh);
 254     static void writeStringLink(const MemberDef *mdef,QCString mem,OutputList& ol);
 255     static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs);
 256     static void  writeRecorUnit(QCString & largs,OutputList& ol ,const MemberDef *mdef);
 257 };
 258
 259 //-------------------------------------------------------------------------------------------------------------------
 260 //-------------- VHDL Flowcharts -------------------------------------------------------------------------------
 261 //-------------------------------------------------------------------------------------------------------------------
 262
 263
 264 //#define DEBUGFLOW
 265
 266 class FlowChart
 267 {
 268   public:
 269     enum nodeTypes {
 270       IF_NO        = 1<<1,
 271       ELSIF_NO     = 1<<2,
 272       ELSE_NO      = 1<<3,
 273       CASE_NO      = 1<<4,
 274       WHEN_NO      = 1<<5,
 275       EXIT_NO      = 1<<6,
 276       END_NO       = 1<<7,
 277       TEXT_NO      = 1<<8,
 278       START_NO     = 1<<9,
 279       ENDIF_NO     = 1<<10,
 280       FOR_NO       = 1<<11,
 281       WHILE_NO     = 1<<12,
 282       END_LOOP     = 1<<13,
 283       END_CASE     = 1<<14,
 284       VARIABLE_NO  = 1<<15,
 285       RETURN_NO    = 1<<16,
 286       LOOP_NO      = 1<<17,
 287       NEXT_NO      = 1<<18,
 288       EMPTY_NO     = 1<<19,
 289       COMMENT_NO   = 1<<20,
 290       BEGIN_NO     = 1<<21
 291     };
 292
 293     //---------- create svg -------------------------------------------------------------
 294     static void createSVG();
 295     static void startDot(FTextStream &t);
 296     static void endDot(FTextStream &t);
 297     static void codify(FTextStream &t,const char *str);
 298     static void writeShape(FTextStream &t,const FlowChart* fl);
 299     static void writeEdge(FTextStream &t,int fl_from,int fl_to,int i,bool bFrom=FALSE,bool bTo=FALSE);
 300     static void writeEdge(FTextStream &t,const FlowChart* fl_from,const FlowChart* fl_to,int i);
 301     static void writeFlowLinks(FTextStream &t);
 302
 303     static QCString getNodeName(int n);
 304     static void colTextNodes();
 305
 306     static int getNextTextLink(const FlowChart* fl,uint index);
 307     static int getNextIfLink(const FlowChart*,uint);
 308     static int getNextNode(int,int);
 309     static int findNode(int index,int stamp,int type);
 310     static int findNode(int index,int type);
 311     static int findNextLoop(int j,int stamp);
 312     static int findPrevLoop(int j,int stamp,bool endif=FALSE);
 313     static int findLabel(int j,QCString &);
 314     static void delFlowList();
 315     static const char* getNodeType(int c);
 316
 317     static void addFlowChart(int type,const char* text,const char* exp,const char * label=NULL);
 318     static void moveToPrevLevel();
 319     static int getTimeStamp();
 320     static void writeFlowChart();
 321     static void alignFuncProc(QCString & q,const ArgumentList*  al,bool isFunc);
 322     static QCString convertNameToFileName();
 323     static void printNode(const FlowChart* n);
 324     static void printFlowTree();
 325     static void buildCommentNodes(FTextStream &t);
 326     static void alignCommentNode(FTextStream &t,QCString com);
 327
 328     static QList<FlowChart> flowList;
 329
 330     FlowChart(int typ,const char*  t,const char* ex,const char* label=0);
 331     ~FlowChart();
 332
 333 private:
 334     int id;
 335     int stamp;
 336     int type;
 337
 338     int line;
 339
 340     QCString label;
 341     QCString text;
 342     QCString exp;
 343 };
 344
 345 #endif