vhdldocgen.h 12 KB
Newer Older
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 7
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
8 9 10 11 12 13 14 15 16 17 18
 * 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

19 20
/** 
 * This class implements functions for parsing and generating 
21 22 23 24 25
 * vhdl documents
 */

#include <qdict.h>
#include <qcstring.h>
26 27 28
#include "layout.h"
#include "arguments.h"
#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

42 43
/** Class for generating documentation specific for VHDL */
class VhdlDocGen  
44 45 46 47 48 49 50 51 52 53
{
  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
    enum VhdlKeyWords
    {
      LIBRARY=1,
      ENTITY,
      PACKAGE_BODY,
      ARCHITECTURE,
      PACKAGE,
      ATTRIBUTE,
      SIGNAL,
      COMPONENT,
      CONSTANT,
      TYPE,
      SUBTYPE,
      FUNCTION,
      RECORD,
      PROCEDURE,
      USE,
      PROCESS,
      PORT,
74
      UNITS,	  
75
      GENERIC,
76
      INSTANTIATION,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
77
      GROUP,
78
      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
    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,
98
                                   QList<Argument>& , 
99 100 101 102 103
                                   QCString& name,
                                   QCString& ret,
                                   bool doc=false);
    // -----------------------------------

104
    static void computeVhdlComponentRelations();
105 106 107 108

    static QCString* findKeyWord(const QCString& word);

    static ClassDef* getPackageName(const QCString& name);
109
    static MemberDef* findMember(const QCString& className, 
110
                                 const QCString& memName);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
111
    static void findAllPackages(ClassDef*);
112 113
    static MemberDef* findMemberDef(ClassDef* cd,
                                const QCString& key,
114
                                MemberListType type);
115 116 117 118 119 120 121 122
    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);

123 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
    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);
150 151 152

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

    // 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&);
181
    static void formatString(const QCString&,OutputList& ol,const MemberDef*);
182

183
    static void writeFormatString(const QCString&,OutputList& ol,const MemberDef*);
184 185 186
    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*);
187
    static bool writeFuncProcDocu(const MemberDef *mdef, OutputList& ol,const ArgumentList* al,bool type=false);
188 189
    static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList *al);

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

    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);

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

    static QCString convertArgumentListToString(const ArgumentList* al,bool f);
    static QCString getProcessNumber();
    static QCString getRecordNumber();
   
211
    static QCString getClassName(const ClassDef*);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
212
    static bool isNumber(const QCString& s);
Dimitri van Heesch's avatar
Dimitri van Heesch committed
213
    static QCString getProtectionName(int prot);
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247

    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);

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

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

    static void writeOverview(OutputList &ol);
    static void writeOverview();
 
 // flowcharts
    static void createFlowChart(const MemberDef*);
    //static void addFlowImage(const FTextStream &,const QCString &);
    
    static void setFlowMember( const MemberDef *flowMember);
    static const MemberDef *getFlowMember();

    static  bool isVhdlClass (const Entry *cu) 
    {
      return cu->spec==VhdlDocGen::ENTITY       ||
             cu->spec==VhdlDocGen::PACKAGE      ||
             cu->spec==VhdlDocGen::ARCHITECTURE ||
             cu->spec==VhdlDocGen::PACKAGE_BODY;
    }

Dimitri van Heesch's avatar
Dimitri van Heesch committed
248
  static void resetCodeVhdlParserState();
249

250
  private:
251
    static void findAllArchitectures(QList<QCString>& ql,const ClassDef *cd);
252 253 254
    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);
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
    static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs);
    static void  writeRecorUnit(QCString & largs,OutputList& ol ,const MemberDef *mdef);
};

//-------------------------------------------------------------------------------------------------------------------
//-------------- VHDL Flowcharts -------------------------------------------------------------------------------
//-------------------------------------------------------------------------------------------------------------------


//#define DEBUGFLOW

class FlowChart
{
  public:
    enum nodeTypes {
      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,
      EMPTY_NO     = 1<<19,
      COMMENT_NO   = 1<<20,
      BEGIN_NO     = 1<<21
    };
292

293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
    //---------- create svg ------------------------------------------------------------- 
    static void createSVG();
    static void startDot(FTextStream &t);
    static void endDot(FTextStream &t);
    static void codify(FTextStream &t,const char *str);
    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);
    static void writeFlowLinks(FTextStream &t);

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

    static int getNextTextLink(const FlowChart* fl,uint index);
    static int getNextIfLink(const FlowChart*,uint);
    static int getNextNode(int,int);
    static int findNode(int index,int stamp,int type);
    static int findNode(int index,int type);
    static int findNextLoop(int j,int stamp);
    static int findPrevLoop(int j,int stamp,bool endif=FALSE);
    static int findLabel(int j,QCString &);
    static void delFlowList();
    static const char* getNodeType(int c);

    static void addFlowChart(int type,const char* text,const char* exp,const char * label=NULL);
    static void moveToPrevLevel();
    static int getTimeStamp();
    static void writeFlowChart();
    static void alignFuncProc(QCString & q,const ArgumentList*  al,bool isFunc);
    static QCString convertNameToFileName();
    static void printNode(const FlowChart* n);
    static void printFlowTree();
    static void buildCommentNodes(FTextStream &t);
    static void alignCommentNode(FTextStream &t,QCString com);

    static QList<FlowChart> flowList;

    FlowChart(int typ,const char*  t,const char* ex,const char* label=0);
    ~FlowChart();

private:
    int id;
    int stamp;
    int type;

    int line;

    QCString label;
    QCString text;
    QCString exp;
343 344
};

345
#endif