src/util.h

   1 /******************************************************************************
   2  *
   3  * $Id: util.h,v 1.49 2001/03/19 19:27:42 root Exp $
   4  *
   5  * Copyright (C) 1997-2012 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17
  18 #ifndef UTIL_H
  19 #define UTIL_H
  20
  21 /*! \file
  22  *  \brief A bunch of utility functions.
  23  */
  24
  25 #include "qtbc.h"
  26 #include <qlist.h>
  27 #include <qtextstream.h>
  28 #include <ctype.h>
  29 #include "sortdict.h"
  30 #include "types.h"
  31
  32 //--------------------------------------------------------------------
  33
  34 class ClassDef;
  35 class FileDef;
  36 class MemberList;
  37 class NamespaceDef;
  38 class FileNameDict;
  39 class ArgumentList;
  40 class OutputList;
  41 class OutputDocInterface;
  42 class MemberDef;
  43 class ExampleSDict;
  44 class ClassSDict;
  45 class BaseClassList;
  46 class GroupDef;
  47 class NamespaceSDict;
  48 class ClassList;
  49 class MemberGroupSDict;
  50 struct TagInfo;
  51 class MemberNameInfoSDict;
  52 struct ListItemInfo;
  53 class PageDef;
  54 struct SectionInfo;
  55 class QDir;
  56 class Definition;
  57 class BufStr;
  58 class QFileInfo;
  59 class QStrList;
  60 class FTextStream;
  61
  62 //--------------------------------------------------------------------
  63
  64 /** Abstract interface for a hyperlinked text fragment. */
  65 class TextGeneratorIntf
  66 {
  67   public:
  68     virtual ~TextGeneratorIntf() {}
  69     virtual void writeString(const char *,bool) const = 0;
  70     virtual void writeBreak(int indent) const = 0;
  71     virtual void writeLink(const char *extRef,const char *file,
  72                       const char *anchor,const char *text
  73                      ) const = 0;
  74 };
  75
  76 /** Implements TextGeneratorIntf for an OutputDocInterface stream. */
  77 class TextGeneratorOLImpl : public TextGeneratorIntf
  78 {
  79   public:
  80     virtual ~TextGeneratorOLImpl() {}
  81     TextGeneratorOLImpl(OutputDocInterface &od);
  82     void writeString(const char *s,bool keepSpaces) const;
  83     void writeBreak(int indent) const;
  84     void writeLink(const char *extRef,const char *file,
  85                    const char *anchor,const char *text
  86                   ) const;
  87   private:
  88     OutputDocInterface &m_od;
  89 };
  90
  91 //--------------------------------------------------------------------
  92
  93 QCString langToString(SrcLangExt lang);
  94 QCString getLanguageSpecificSeparator(SrcLangExt lang,bool classScope=FALSE);
  95
  96 //--------------------------------------------------------------------
  97
  98 void linkifyText(const TextGeneratorIntf &ol,
  99                  Definition *scope,
 100                  FileDef *fileScope,
 101                  Definition *self,
 102                  const char *text,
 103                  bool autoBreak=FALSE,
 104                  bool external=TRUE,
 105                  bool keepSpaces=FALSE,
 106                  int indentLevel=0
 107                 );
 108
 109 void setAnchors(ClassDef *cd,char id,MemberList *ml,int groupId=-1);
 110
 111 QCString fileToString(const char *name,bool filter=FALSE,bool isSourceCode=FALSE);
 112
 113 QCString dateToString(bool);
 114
 115 bool getDefs(const QCString &scopeName,
 116                     const QCString &memberName,
 117                     const char *,
 118                     MemberDef *&md,
 119                     ClassDef *&cd,
 120                     FileDef *&fd,
 121                     NamespaceDef *&nd,
 122                     GroupDef *&gd,
 123                     bool forceEmptyScope=FALSE,
 124                     FileDef *currentFile=0,
 125                     bool checkCV=FALSE,
 126                     const char *forceTagFile=0
 127                    );
 128
 129 QCString getFileFilter(const char* name,bool isSourceCode);
 130
 131 bool resolveRef(/* in */  const char *scName,
 132                 /* in */  const char *name,
 133                 /* in */  bool inSeeBlock,
 134                 /* out */ Definition **resContext,
 135                 /* out */ MemberDef  **resMember,
 136                 /* in */  bool lookForSpecializations = TRUE,
 137                 /* in */  FileDef *currentFile = 0,
 138                 /* in */  bool checkScope = FALSE
 139                );
 140
 141 bool resolveLink(/* in */  const char *scName,
 142                  /* in */  const char *lr,
 143                  /* in */  bool inSeeBlock,
 144                  /* out */ Definition **resContext,
 145                  /* out */ QCString &resAnchor
 146                 );
 147
 148 //bool generateRef(OutputDocInterface &od,const char *,
 149 //                        const char *,bool inSeeBlock,const char * =0);
 150
 151 bool generateLink(OutputDocInterface &od,const char *,
 152                          const char *,bool inSeeBlock,const char *);
 153
 154 void generateFileRef(OutputDocInterface &od,const char *,
 155                              const char *linkTxt=0);
 156
 157 void writePageRef(OutputDocInterface &od,const char *cn,const char *mn);
 158
 159 QCString getCanonicalTemplateSpec(Definition *d,FileDef *fs,const QCString& spec);
 160
 161 bool matchArguments2(Definition *srcScope,FileDef *srcFileScope,ArgumentList *srcAl,
 162                      Definition *dstScope,FileDef *dstFileScope,ArgumentList *dstAl,
 163                      bool checkCV
 164                     );
 165
 166 void mergeArguments(ArgumentList *,ArgumentList *,bool forceNameOverwrite=FALSE);
 167
 168 QCString substituteClassNames(const QCString &s);
 169
 170 QCString substitute(const char *s,const char *src,const char *dst);
 171
 172 QCString clearBlock(const char *s,const char *begin,const char *end);
 173
 174 QCString selectBlock(const QCString& s,const QCString &name,bool which);
 175
 176 QCString resolveDefines(const char *n);
 177
 178 ClassDef *getClass(const char *key);
 179
 180 ClassDef *getResolvedClass(Definition *scope,
 181                            FileDef *fileScope,
 182                            const char *key,
 183                            MemberDef **pTypeDef=0,
 184                            QCString *pTemplSpec=0,
 185                            bool mayBeUnlinkable=FALSE,
 186                            bool mayBeHidden=FALSE,
 187                            QCString *pResolvedType=0);
 188
 189 NamespaceDef *getResolvedNamespace(const char *key);
 190
 191 FileDef *findFileDef(const FileNameDict *fnDict,const char *n,
 192                 bool &ambig);
 193
 194 QCString showFileDefMatches(const FileNameDict *fnDict,const char *n);
 195
 196 int guessSection(const char *name);
 197
 198 inline bool isId(int c)
 199 {
 200   return c=='_' || c>=128 || c<0 || isalnum(c);
 201 }
 202
 203 QCString removeRedundantWhiteSpace(const QCString &s);
 204
 205 QCString argListToString(ArgumentList *al,bool useCanonicalType=FALSE,bool showDefVals=TRUE);
 206
 207 QCString tempArgListToString(ArgumentList *al);
 208
 209 QCString generateMarker(int id);
 210
 211 void writeExample(OutputList &ol,ExampleSDict *el);
 212
 213 QCString stripAnonymousNamespaceScope(const QCString &s);
 214
 215 QCString stripFromPath(const QCString &path);
 216
 217 QCString stripFromIncludePath(const QCString &path);
 218
 219 bool rightScopeMatch(const QCString &scope, const QCString &name);
 220
 221 bool leftScopeMatch(const QCString &scope, const QCString &name);
 222
 223 QCString substituteKeywords(const QCString &s,const char *title,
 224          const char *projName,const char *projNum,const char *projBrief);
 225
 226 int getPrefixIndex(const QCString &name);
 227
 228 QCString removeAnonymousScopes(const QCString &s);
 229
 230 QCString replaceAnonymousScopes(const QCString &s,const char *replacement=0);
 231
 232 void initClassHierarchy(ClassSDict *cl);
 233
 234 bool hasVisibleRoot(BaseClassList *bcl);
 235
 236 int minClassDistance(const ClassDef *cd,const ClassDef *bcd,int level=0);
 237 Protection classInheritedProtectionLevel(ClassDef *cd,ClassDef *bcd,Protection prot=Public,int level=0);
 238
 239 QCString convertNameToFile(const char *name,bool allowDots=FALSE,bool allowUnderscore=FALSE);
 240
 241 void extractNamespaceName(const QCString &scopeName,
 242                           QCString &className,QCString &namespaceName,
 243                           bool allowEmptyClass=FALSE);
 244
 245 QCString insertTemplateSpecifierInScope(const QCString &scope,const QCString &templ);
 246
 247 QCString stripScope(const char *name);
 248
 249 QCString convertToHtml(const char *s,bool keepEntities=TRUE);
 250
 251 QCString convertToXML(const char *s);
 252
 253 QCString convertToJSString(const char *s);
 254
 255 QCString getOverloadDocs();
 256
 257 void addMembersToMemberGroup(/* in */     MemberList *ml,
 258                              /* in,out */ MemberGroupSDict **ppMemberGroupSDict,
 259                              /* in */     Definition *context);
 260
 261 int extractClassNameFromType(const QCString &type,int &pos,
 262                               QCString &name,QCString &templSpec,SrcLangExt=SrcLangExt_Unknown);
 263
 264 QCString substituteTemplateArgumentsInString(
 265        const QCString &name,
 266        ArgumentList *formalArgs,
 267        ArgumentList *actualArgs);
 268
 269 QList<ArgumentList> *copyArgumentLists(const QList<ArgumentList> *srcLists);
 270
 271 QCString stripTemplateSpecifiersFromScope(const QCString &fullName,
 272                                           bool parentOnly=TRUE,
 273                                           QCString *lastScopeStripped=0);
 274
 275 QCString resolveTypeDef(Definition *d,const QCString &name,
 276                         Definition **typedefContext=0);
 277
 278 QCString mergeScopes(const QCString &leftScope,const QCString &rightScope);
 279
 280 int getScopeFragment(const QCString &s,int p,int *l);
 281
 282 int filterCRLF(char *buf,int len);
 283
 284 void addRefItem(const QList<ListItemInfo> *sli,const char *prefix,
 285                 const char *key,
 286                 const char *name,const char *title,const char *args);
 287
 288 PageDef *addRelatedPage(const char *name,const QCString &ptitle,
 289                            const QCString &doc,QList<SectionInfo> *anchors,
 290                            const char *fileName,int startLine,
 291                            const QList<ListItemInfo> *sli,
 292                            GroupDef *gd=0,
 293                            TagInfo *tagInfo=0,
 294                            SrcLangExt lang=SrcLangExt_Unknown
 295                           );
 296
 297 QCString escapeCharsInString(const char *name,bool allowDots,bool allowUnderscore=FALSE);
 298
 299 void addGroupListToTitle(OutputList &ol,Definition *d);
 300
 301 void filterLatexString(FTextStream &t,const char *str,
 302                        bool insideTabbing=FALSE,
 303                        bool insidePre=FALSE,
 304                        bool insideItem=FALSE);
 305
 306 QCString rtfFormatBmkStr(const char *name);
 307
 308 QCString linkToText(SrcLangExt lang,const char *link,bool isFileName);
 309
 310 QCString stripExtension(const char *fName);
 311
 312 void replaceNamespaceAliases(QCString &scope,int i);
 313
 314 int isAccessibleFrom(Definition *scope,FileDef *fileScope,Definition *item);
 315
 316 int isAccessibleFromWithExpScope(Definition *scope,FileDef *fileScope,Definition *item,
 317                      const QCString &explicitScopePart);
 318
 319 int computeQualifiedIndex(const QCString &name);
 320
 321 void addDirPrefix(QCString &fileName);
 322
 323 QCString relativePathToRoot(const char *name);
 324
 325 void createSubDirs(QDir &d);
 326
 327 QCString stripPath(const char *s);
 328
 329 bool containsWord(const QCString &s,const QCString &word);
 330
 331 bool findAndRemoveWord(QCString &s,const QCString &word);
 332
 333 QCString stripLeadingAndTrailingEmptyLines(const QCString &s,int &docLine);
 334
 335 //void stringToSearchIndex(const QCString &docUrlBase,const QCString &title,
 336 //                         const QCString &str, bool priority=FALSE,
 337 //                         const QCString &anchor="");
 338
 339 bool updateLanguageMapping(const QCString &extension,const QCString &parser);
 340 SrcLangExt getLanguageFromFileName(const QCString fileName);
 341 void initDefaultExtensionMapping();
 342
 343 MemberDef *getMemberFromSymbol(Definition *scope,FileDef *fileScope,
 344                                 const char *n);
 345 bool checkIfTypedef(Definition *scope,FileDef *fileScope,const char *n);
 346
 347 ClassDef *newResolveTypedef(FileDef *fileScope,MemberDef *md,
 348                             MemberDef **pMemType=0,QCString *pTemplSpec=0,
 349                             QCString *pResolvedType=0,
 350                             ArgumentList *actTemplParams=0);
 351
 352 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QCString &doc,const QCString &fileName,int lineNr);
 353
 354 QCString transcodeCharacterStringToUTF8(const QCString &input);
 355
 356 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);
 357
 358 QCString extractAliasArgs(const QCString &args,int pos);
 359
 360 int countAliasArguments(const QCString argList);
 361
 362 //QCString replaceAliasArguments(const QCString &aliasValue,const QCString &argList);
 363
 364 QCString resolveAliasCmd(const QCString aliasCmd);
 365 QCString expandAlias(const QCString &aliasName,const QCString &aliasValue);
 366
 367 void writeTypeConstraints(OutputList &ol,Definition *d,ArgumentList *al);
 368
 369 QCString convertCharEntitiesToUTF8(const QCString &s);
 370
 371 void stackTrace();
 372
 373 bool readInputFile(const char *fileName,BufStr &inBuf);
 374 QCString filterTitle(const QCString &title);
 375
 376 bool patternMatch(const QFileInfo &fi,const QStrList *patList);
 377
 378 QCString externalLinkTarget();
 379 QCString externalRef(const QCString &relPath,const QCString &ref,bool href);
 380 int nextUtf8CharPosition(const QCString &utf8Str,int len,int startPos);
 381
 382 /** Data associated with a HSV colored image. */
 383 struct ColoredImgDataItem
 384 {
 385   const char *name;
 386   unsigned short width;
 387   unsigned short height;
 388   unsigned char *content;
 389   unsigned char *alpha;
 390 };
 391
 392 void writeColoredImgData(const char *dir,ColoredImgDataItem data[]);
 393 QCString replaceColorMarkers(const char *str);
 394
 395 bool copyFile(const QCString &src,const QCString &dest);
 396 QCString extractBlock(const QCString text,const QCString marker);
 397
 398 QCString correctURL(const QCString &url,const QCString &relPath);
 399
 400 QCString processMarkup(const QCString &s);
 401
 402 bool protectionLevelVisible(Protection prot);
 403
 404 QCString stripIndentation(const QCString &s);
 405
 406 bool fileVisibleInIndex(FileDef *fd,bool &genSourceFile);
 407
 408 #endif
 409