vhdldocgen.h 12 KB
Newer Older
1 2
/******************************************************************************
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
3
 * Copyright (C) 1997-2013 by Dimitri van Heesch.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */

#ifndef VHDLDOCGEN_H
#define VHDLDOCGEN_H

/** 
 * This class implements functions for parsing and generating 
 * vhdl documents
 */

#include <qdict.h>
#include <qcstring.h>
26
#include "layout.h"
27
#include "arguments.h"
28
#include "entry.h"
29 30 31

class Entry;
class ClassDef;
32
class MemberList;
33
class MemberDef;
34 35 36 37 38 39
class FTextStream;
class OutputList;
class Definition;
class GroupDef;
class FileDef;
class NamespaceDef;
Dimitri van Heesch's avatar
Dimitri van Heesch committed
40
struct Argument;
41

Dimitri van Heesch's avatar
Dimitri van Heesch committed
42
/** Class for generating documentation specific for VHDL */
43 44 45 46 47 48 49 50 51 52 53
class VhdlDocGen  
{
  public:

    enum VhdlClasses       // Overlays: Protection
    {
      ENTITYCLASS,         // Overlays: Public
      PACKBODYCLASS,       // Overlays: Protected
      ARCHITECTURECLASS,   // Overlays: Private
      PACKAGECLASS         // Overlays: Package
    };
54

55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
    enum VhdlKeyWords
    {
      LIBRARY=1,
      ENTITY,
      PACKAGE_BODY,
      ARCHITECTURE,
      PACKAGE,
      ATTRIBUTE,
      SIGNAL,
      COMPONENT,
      CONSTANT,
      TYPE,
      SUBTYPE,
      FUNCTION,
      RECORD,
      PROCEDURE,
      USE,
      PROCESS,
      PORT,
      UNITS,	  
      GENERIC,
76
      INSTANTIATION,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
77 78
      GROUP,
      VFILE,   
Dimitri van Heesch's avatar
Dimitri van Heesch committed
79 80
      SHAREDVARIABLE,
      CONFIG,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
81
      ALIAS,
82 83
      MISCELLANEOUS,
      UCF_CONST
84 85 86 87 88
    };

    VhdlDocGen();
    virtual ~VhdlDocGen();
    static void init();
89
    static QCString convertFileNameToClassName(QCString name);
90
    // --- used by vhdlscanner.l -----------
91
    
92 93
    static bool isSubClass(ClassDef* cd,ClassDef *scd, bool followInstances,int level);

94 95 96 97 98 99 100 101 102 103
    static QCString getIndexWord(const char* ,int index);
    static bool     deleteCharRev(QCString &s,char c);
    static void     deleteAllChars(QCString &s,char c);
    static void     parseFuncProto(const char* text,
                                   QList<Argument>& , 
                                   QCString& name,
                                   QCString& ret,
                                   bool doc=false);
    // -----------------------------------

104
    static void computeVhdlComponentRelations();
105 106 107 108 109 110 111 112 113 114

    static QCString* findKeyWord(const QCString& word);

    static ClassDef* getPackageName(const QCString& name);
    static MemberDef* findMember(const QCString& className, 
                                 const QCString& memName);
    static void findAllPackages(const QCString& className,
                                QDict<QCString>&);
    static MemberDef* findMemberDef(ClassDef* cd,
                                const QCString& key,
115
                                MemberListType type);
116 117 118 119 120 121 122 123
    static ClassDef *getClass(const char *name);
    static MemberDef* findFunction(const QList<Argument> &ql,
                                   const QCString& name,
                                   const QCString& package, bool type);
    static QCString getClassTitle(const ClassDef*);
    static void writeInlineClassLink(const ClassDef*,
                                     OutputList &ol);

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
    static bool isConstraint(const MemberDef *mdef);
    static bool isConfig(const MemberDef *mdef);
    static bool isAlias(const MemberDef *mdef);
    static bool isLibrary(const MemberDef *mdef);
    static bool isGeneric(const MemberDef *mdef);
    static bool isPort(const MemberDef *mdef);
    static bool isComponent(const MemberDef *mdef);
    static bool isPackage(const MemberDef *mdef);
    static bool isEntity(const MemberDef *mdef);
    static bool isConstant(const MemberDef *mdef);
    static bool isVType(const MemberDef *mdef);
    static bool isSubType(const MemberDef *mdef);
    static bool isVhdlFunction(const MemberDef *mdef);
    static bool isProcess(const MemberDef *mdef);
    static bool isSignal(const MemberDef *mdef);
    static bool isAttribute(const MemberDef *mdef);
    static bool isSignals(const MemberDef *mdef);
    static bool isProcedure(const MemberDef *mdef);
    static bool isRecord(const MemberDef *mdef);
    static bool isArchitecture(const MemberDef *mdef);
    static bool isUnit(const MemberDef *mdef);
    static bool isPackageBody(const MemberDef *mdef);
    static bool isVariable(const MemberDef *mdef);
    static bool isFile(const MemberDef *mdef);
    static bool isGroup(const MemberDef *mdef);
    static bool isCompInst(const MemberDef *mdef);
    static bool isMisc(const MemberDef *mdef);
151 152 153 154

    //-----------------------------------------------------
    // translatable items
    
155 156
    static QCString trTypeString(uint64 type);
    static QCString trVhdlType(uint64 type,bool sing=true);
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181

    // trClassHierarchy.
    static QCString trDesignUnitHierarchy();

    // trCompoundList
    static QCString trDesignUnitList();

    // trCompoundMembers.
    static QCString trDesignUnitMembers();

    // trCompoundListDescription
    static QCString trDesignUnitListDescription();

    // trCompounds
    static QCString trDesignUnits();

    // trCompoundIndex
    static QCString trDesignUnitIndex();

    // trFunctions
    static QCString trFunctionAndProc();

    //-----------------------------------------------------

    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 186 187
    static void writeFunctionProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
    static void writeProcessProto(OutputList& ol,const ArgumentList *al,const MemberDef*);
    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 190
    static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList *al);

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 196 197 198 199 200 201 202 203 204 205

    static void writeVHDLDeclaration(MemberDef* mdef,OutputList &ol,
        ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
        bool inGroup);

    static void writePlainVHDLDeclarations(MemberList* ml,OutputList &ol,
        ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,int specifier);

    static void writeVHDLDeclarations(MemberList* ml,OutputList &ol,
        ClassDef *cd,NamespaceDef *nd,FileDef *fd,GroupDef *gd,
        const char *title,const char *subtitle,bool showEnumValues,int type);

206 207 208 209 210 211
    static bool writeClassType(ClassDef *&,OutputList &ol ,QCString & cname);

    static QCString convertArgumentListToString(const ArgumentList* al,bool f);
    static QCString getProcessNumber();
    static QCString getRecordNumber();
   
212
    static QCString getClassName(const ClassDef*);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
213
    static bool isNumber(const QCString& s);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
214
    static QCString getProtectionName(int prot);
215

216 217 218 219 220 221
    static void parseUCF(const char*  input,Entry* entity,QCString f,bool vendor);
    static bool findConstraintFile( LayoutNavEntry *lne);

    static ClassDef*  findArchitecture(const ClassDef *cd);
    static ClassDef*  findArchitecture(QCString identifier, QCString entity_name);

222
    
223 224 225
    static void writeSource(MemberDef *mdef,OutputList& ol,QCString & cname);
    static void writeAlphbeticalClass(OutputList& ol,const ClassDef* cd,const QCString &);

226 227
    static QCString  parseForConfig(QCString & entity,QCString & arch);
    static QCString  parseForBinding(QCString & entity,QCString & arch);
228
    static void addBaseClass(ClassDef* cd,ClassDef *ent);
229
    static ClassDef* findVhdlClass(const char *className );
230

Dimitri van Heesch's avatar
Dimitri van Heesch committed
231 232
    static void writeOverview(OutputList &ol);
    static void writeOverview();
233 234
 
 // flowcharts
235 236
    static void createFlowChart(const MemberDef*);
    //static void addFlowImage(const FTextStream &,const QCString &);
237 238
    
    static void setFlowMember( const MemberDef *flowMember);
239
    static const MemberDef *getFlowMember();
Dimitri van Heesch's avatar
Dimitri van Heesch committed
240

241 242 243 244 245 246 247 248 249 250
    static  bool isVhdlClass (const Entry *cu) 
    {
      return cu->spec==VhdlDocGen::ENTITY       ||
             cu->spec==VhdlDocGen::PACKAGE      ||
             cu->spec==VhdlDocGen::ARCHITECTURE ||
             cu->spec==VhdlDocGen::PACKAGE_BODY;
    }



251
  private:
252
    static void findAllArchitectures(QList<QCString>& ql,const ClassDef *cd);
253 254 255
    static bool compareArgList(ArgumentList*,ArgumentList*);
    static void writeVhdlLink(const ClassDef* cdd ,OutputList& ol,QCString& type,QCString& name,QCString& beh);
    static void writeStringLink(const MemberDef *mdef,QCString mem,OutputList& ol);
256 257
    static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs);
    static void  writeRecorUnit(QCString & largs,OutputList& ol ,const MemberDef *mdef);
258 259
};

260 261 262 263 264
//-------------------------------------------------------------------------------------------------------------------
//-------------- VHDL Flowcharts -------------------------------------------------------------------------------
//-------------------------------------------------------------------------------------------------------------------


Dimitri van Heesch's avatar
Dimitri van Heesch committed
265
//#define DEBUGFLOW
266

Dimitri van Heesch's avatar
Dimitri van Heesch committed
267
class FlowChart
268 269
{
  public:
Dimitri van Heesch's avatar
Dimitri van Heesch committed
270
    enum nodeTypes {
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
      IF_NO        = 1<<1,
      ELSIF_NO     = 1<<2,
      ELSE_NO      = 1<<3,
      CASE_NO      = 1<<4,
      WHEN_NO      = 1<<5,
      EXIT_NO      = 1<<6,
      END_NO       = 1<<7,
      TEXT_NO      = 1<<8,
      START_NO     = 1<<9,
      ENDIF_NO     = 1<<10,
      FOR_NO       = 1<<11,
      WHILE_NO     = 1<<12,
      END_LOOP     = 1<<13,
      END_CASE     = 1<<14,
      VARIABLE_NO  = 1<<15,
      RETURN_NO    = 1<<16,
      LOOP_NO      = 1<<17,
      NEXT_NO      = 1<<18,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
289 290 291
      EMPTY_NO     = 1<<19,
      COMMENT_NO   = 1<<20,
      BEGIN_NO     = 1<<21
292 293 294 295 296 297 298
    };

    //---------- create svg ------------------------------------------------------------- 
    static void createSVG();
    static void startDot(FTextStream &t);
    static void endDot(FTextStream &t);
    static void codify(FTextStream &t,const char *str);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
299 300 301
    static void writeShape(FTextStream &t,const FlowChart* fl);
    static void writeEdge(FTextStream &t,int fl_from,int fl_to,int i,bool bFrom=FALSE,bool bTo=FALSE);
    static void writeEdge(FTextStream &t,const FlowChart* fl_from,const FlowChart* fl_to,int i);
302 303 304 305 306
    static void writeFlowLinks(FTextStream &t);

    static QCString getNodeName(int n);
    static void colTextNodes();

Dimitri van Heesch's avatar
Dimitri van Heesch committed
307 308 309
    static int getNextTextLink(const FlowChart* fl,uint index);
    static int getNextIfLink(const FlowChart*,uint);
    static int getNextNode(int,int);
310 311 312
    static int findNode(int index,int stamp,int type);
    static int findNode(int index,int type);
    static int findNextLoop(int j,int stamp);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
313
    static int findPrevLoop(int j,int stamp,bool endif=FALSE);
314 315 316 317
    static int findLabel(int j,QCString &);
    static void delFlowList();
    static const char* getNodeType(int c);

Dimitri van Heesch's avatar
Dimitri van Heesch committed
318
    static void addFlowChart(int type,const char* text,const char* exp,const char * label=NULL);
319 320
    static void moveToPrevLevel();
    static int getTimeStamp();
Dimitri van Heesch's avatar
Dimitri van Heesch committed
321
    static void writeFlowChart();
322 323
    static void alignFuncProc(QCString & q,const ArgumentList*  al,bool isFunc);
    static QCString convertNameToFileName();
Dimitri van Heesch's avatar
Dimitri van Heesch committed
324 325 326 327
    static void printNode(const FlowChart* n);
    static void printFlowTree();
    static void buildCommentNodes(FTextStream &t);
    static void alignCommentNode(FTextStream &t,QCString com);
328

Dimitri van Heesch's avatar
Dimitri van Heesch committed
329
    static QList<FlowChart> flowList;
330

Dimitri van Heesch's avatar
Dimitri van Heesch committed
331 332
    FlowChart(int typ,const char*  t,const char* ex,const char* label=0);
    ~FlowChart();
333

334
private:
335 336 337 338
    int id;
    int stamp;
    int type;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
339 340
    int line;

341 342 343 344 345
    QCString label;
    QCString text;
    QCString exp;
};

346
#endif