src/util.h

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 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 <qlist.h>
  26 #include <ctype.h>
  27 #include "types.h"
  28 #include "sortdict.h"
  29 #include "docparser.h"
  30 #include "classdef.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 class QFile;
  62
  63 //--------------------------------------------------------------------
  64
  65 /** Abstract interface for a hyperlinked text fragment. */
  66 class TextGeneratorIntf
  67 {
  68   public:
  69     virtual ~TextGeneratorIntf() {}
  70     virtual void writeString(const char *,bool) const = 0;
  71     virtual void writeBreak(int indent) const = 0;
  72     virtual void writeLink(const char *extRef,const char *file,
  73                       const char *anchor,const char *text
  74                      ) const = 0;
  75 };
  76
  77 /** Implements TextGeneratorIntf for an OutputDocInterface stream. */
  78 class TextGeneratorOLImpl : public TextGeneratorIntf
  79 {
  80   public:
  81     virtual ~TextGeneratorOLImpl() {}
  82     TextGeneratorOLImpl(OutputDocInterface &od);
  83     void writeString(const char *s,bool keepSpaces) const;
  84     void writeBreak(int indent) const;
  85     void writeLink(const char *extRef,const char *file,
  86                    const char *anchor,const char *text
  87                   ) const;
  88   private:
  89     OutputDocInterface &m_od;
  90 };
  91
  92 //--------------------------------------------------------------------
  93
  94 /** @brief maps a unicode character code to a list of T::ElementType's
  95  */
  96 template<class T>
  97 class LetterToIndexMap : public SIntDict<T>
  98 {
  99   public:
 100     LetterToIndexMap() { SIntDict<T>::setAutoDelete(TRUE); }
 101     void append(uint letter,typename T::ElementType *elem)
 102     {
 103       T *l = SIntDict<T>::find((int)letter);
 104       if (l==0)
 105       {
 106         l = new T(letter);
 107         SIntDict<T>::inSort((int)letter,l);
 108       }
 109       l->append(elem);
 110     }
 111   private:
 112     int compareValues(const T *l1, const T *l2) const
 113     {
 114       return (int)l1->letter()-(int)l2->letter();
 115     }
 116 };
 117
 118 //--------------------------------------------------------------------
 119
 120 QCString langToString(SrcLangExt lang);
 121 QCString getLanguageSpecificSeparator(SrcLangExt lang,bool classScope=FALSE);
 122
 123 //--------------------------------------------------------------------
 124
 125 void linkifyText(const TextGeneratorIntf &ol,
 126                  const Definition *scope,
 127                  const FileDef *fileScope,
 128                  const Definition *self,
 129                  const char *text,
 130                  bool autoBreak=FALSE,
 131                  bool external=TRUE,
 132                  bool keepSpaces=FALSE,
 133                  int indentLevel=0
 134                 );
 135
 136 void setAnchors(MemberList *ml);
 137
 138 QCString fileToString(const char *name,bool filter=FALSE,bool isSourceCode=FALSE);
 139
 140 QCString dateToString(bool);
 141
 142 bool getDefs(const QCString &scopeName,
 143                     const QCString &memberName,
 144                     const char *,
 145                     MemberDef *&md,
 146                     ClassDef *&cd,
 147                     FileDef *&fd,
 148                     NamespaceDef *&nd,
 149                     GroupDef *&gd,
 150                     bool forceEmptyScope=FALSE,
 151                     FileDef *currentFile=0,
 152                     bool checkCV=FALSE,
 153                     const char *forceTagFile=0
 154                    );
 155
 156 QCString getFileFilter(const char* name,bool isSourceCode);
 157
 158 bool resolveRef(/* in */  const char *scName,
 159                 /* in */  const char *name,
 160                 /* in */  bool inSeeBlock,
 161                 /* out */ Definition **resContext,
 162                 /* out */ MemberDef  **resMember,
 163                 /* in */  bool lookForSpecializations = TRUE,
 164                 /* in */  FileDef *currentFile = 0,
 165                 /* in */  bool checkScope = FALSE
 166                );
 167
 168 bool resolveLink(/* in */  const char *scName,
 169                  /* in */  const char *lr,
 170                  /* in */  bool inSeeBlock,
 171                  /* out */ Definition **resContext,
 172                  /* out */ QCString &resAnchor
 173                 );
 174
 175 //bool generateRef(OutputDocInterface &od,const char *,
 176 //                        const char *,bool inSeeBlock,const char * =0);
 177
 178 bool generateLink(OutputDocInterface &od,const char *,
 179                          const char *,bool inSeeBlock,const char *);
 180
 181 void generateFileRef(OutputDocInterface &od,const char *,
 182                              const char *linkTxt=0);
 183
 184 void writePageRef(OutputDocInterface &od,const char *cn,const char *mn);
 185
 186 QCString getCanonicalTemplateSpec(Definition *d,FileDef *fs,const QCString& spec);
 187
 188 bool matchArguments2(Definition *srcScope,FileDef *srcFileScope,ArgumentList *srcAl,
 189                      Definition *dstScope,FileDef *dstFileScope,ArgumentList *dstAl,
 190                      bool checkCV
 191                     );
 192
 193 void mergeArguments(ArgumentList *,ArgumentList *,bool forceNameOverwrite=FALSE);
 194
 195 QCString substituteClassNames(const QCString &s);
 196
 197 QCString substitute(const QCString &s,const QCString &src,const QCString &dst);
 198 QCString substitute(const QCString &s,const QCString &src,const QCString &dst,int skip_seq);
 199 QCString substitute(const QCString &s,char srcChar,char dstChar);
 200
 201 QCString clearBlock(const char *s,const char *begin,const char *end);
 202
 203 QCString selectBlock(const QCString& s,const QCString &name,bool which);
 204
 205 QCString resolveDefines(const char *n);
 206
 207 ClassDef *getClass(const char *key);
 208
 209 ClassDef *getResolvedClass(const Definition *scope,
 210                            const FileDef *fileScope,
 211                            const char *key,
 212                            MemberDef **pTypeDef=0,
 213                            QCString *pTemplSpec=0,
 214                            bool mayBeUnlinkable=FALSE,
 215                            bool mayBeHidden=FALSE,
 216                            QCString *pResolvedType=0);
 217
 218 NamespaceDef *getResolvedNamespace(const char *key);
 219
 220 FileDef *findFileDef(const FileNameDict *fnDict,const char *n,
 221                 bool &ambig);
 222
 223 QCString showFileDefMatches(const FileNameDict *fnDict,const char *n);
 224
 225 int guessSection(const char *name);
 226
 227 inline bool isId(int c)
 228 {
 229   return c=='_' || c>=128 || c<0 || isalnum(c);
 230 }
 231
 232 QCString removeRedundantWhiteSpace(const QCString &s);
 233
 234 QCString argListToString(ArgumentList *al,bool useCanonicalType=FALSE,bool showDefVals=TRUE);
 235
 236 QCString tempArgListToString(ArgumentList *al,SrcLangExt lang);
 237
 238 QCString generateMarker(int id);
 239
 240 void writeExample(OutputList &ol,ExampleSDict *el);
 241
 242 QCString stripAnonymousNamespaceScope(const QCString &s);
 243
 244 QCString stripFromPath(const QCString &path);
 245
 246 QCString stripFromIncludePath(const QCString &path);
 247
 248 bool rightScopeMatch(const QCString &scope, const QCString &name);
 249
 250 bool leftScopeMatch(const QCString &scope, const QCString &name);
 251
 252 QCString substituteKeywords(const QCString &s,const char *title,
 253          const char *projName,const char *projNum,const char *projBrief);
 254
 255 int getPrefixIndex(const QCString &name);
 256
 257 QCString removeAnonymousScopes(const QCString &s);
 258
 259 QCString replaceAnonymousScopes(const QCString &s,const char *replacement=0);
 260
 261 void initClassHierarchy(ClassSDict *cl);
 262
 263 bool hasVisibleRoot(BaseClassList *bcl);
 264 bool classHasVisibleChildren(ClassDef *cd);
 265 bool namespaceHasVisibleChild(NamespaceDef *nd,bool includeClasses,bool filterClasses,ClassDef::CompoundType ct);
 266 bool classVisibleInIndex(ClassDef *cd);
 267
 268 int minClassDistance(const ClassDef *cd,const ClassDef *bcd,int level=0);
 269 Protection classInheritedProtectionLevel(ClassDef *cd,ClassDef *bcd,Protection prot=Public,int level=0);
 270
 271 QCString convertNameToFile(const char *name,bool allowDots=FALSE,bool allowUnderscore=FALSE);
 272
 273 void extractNamespaceName(const QCString &scopeName,
 274                           QCString &className,QCString &namespaceName,
 275                           bool allowEmptyClass=FALSE);
 276
 277 QCString insertTemplateSpecifierInScope(const QCString &scope,const QCString &templ);
 278
 279 QCString stripScope(const char *name);
 280
 281 QCString convertToId(const char *s);
 282
 283 QCString convertToHtml(const char *s,bool keepEntities=TRUE);
 284
 285 QCString convertToLaTeX(const QCString &s,bool insideTabbing=FALSE,bool keepSpaces=FALSE);
 286
 287 QCString convertToXML(const char *s);
 288
 289 QCString convertToDocBook(const char *s);
 290
 291 QCString convertToJSString(const char *s, bool applyTextDir = true);
 292
 293 QCString getOverloadDocs();
 294
 295 void addMembersToMemberGroup(/* in */     MemberList *ml,
 296                              /* in,out */ MemberGroupSDict **ppMemberGroupSDict,
 297                              /* in */     Definition *context);
 298
 299 int extractClassNameFromType(const QCString &type,int &pos,
 300                               QCString &name,QCString &templSpec,SrcLangExt=SrcLangExt_Unknown);
 301
 302 QCString normalizeNonTemplateArgumentsInString(
 303        const QCString &name,
 304        Definition *context,
 305        const ArgumentList *formalArgs);
 306
 307 QCString substituteTemplateArgumentsInString(
 308        const QCString &name,
 309        ArgumentList *formalArgs,
 310        ArgumentList *actualArgs);
 311
 312 QList<ArgumentList> *copyArgumentLists(const QList<ArgumentList> *srcLists);
 313
 314 QCString stripTemplateSpecifiersFromScope(const QCString &fullName,
 315                                           bool parentOnly=TRUE,
 316                                           QCString *lastScopeStripped=0);
 317
 318 QCString resolveTypeDef(Definition *d,const QCString &name,
 319                         Definition **typedefContext=0);
 320
 321 QCString mergeScopes(const QCString &leftScope,const QCString &rightScope);
 322
 323 int getScopeFragment(const QCString &s,int p,int *l);
 324
 325 int filterCRLF(char *buf,int len);
 326
 327 void addRefItem(const QList<ListItemInfo> *sli,const char *prefix,
 328                 const char *key,
 329                 const char *name,const char *title,const char *args,Definition *scope);
 330
 331 PageDef *addRelatedPage(const char *name,const QCString &ptitle,
 332                            const QCString &doc,QList<SectionInfo> *anchors,
 333                            const char *fileName,int startLine,
 334                            const QList<ListItemInfo> *sli,
 335                            GroupDef *gd=0,
 336                            TagInfo *tagInfo=0,
 337                            SrcLangExt lang=SrcLangExt_Unknown
 338                           );
 339
 340 QCString escapeCharsInString(const char *name,bool allowDots,bool allowUnderscore=FALSE);
 341
 342 void addGroupListToTitle(OutputList &ol,Definition *d);
 343
 344 void filterLatexString(FTextStream &t,const char *str,
 345                        bool insideTabbing=FALSE,
 346                        bool insidePre=FALSE,
 347                        bool insideItem=FALSE,
 348                        bool keepSpaces=FALSE);
 349
 350 QCString latexEscapeLabelName(const char *s);
 351 QCString latexEscapeIndexChars(const char *s);
 352 QCString latexEscapePDFString(const char *s);
 353 QCString latexFilterURL(const char *s);
 354
 355 QCString rtfFormatBmkStr(const char *name);
 356
 357 QCString linkToText(SrcLangExt lang,const char *link,bool isFileName);
 358
 359 bool checkExtension(const char *fName, const char *ext);
 360
 361 QCString stripExtensionGeneral(const char *fName, const char *ext);
 362
 363 QCString stripExtension(const char *fName);
 364
 365 void replaceNamespaceAliases(QCString &scope,int i);
 366
 367 int isAccessibleFrom(const Definition *scope,const FileDef *fileScope,const Definition *item);
 368
 369 int isAccessibleFromWithExpScope(const Definition *scope,const FileDef *fileScope,const Definition *item,
 370                      const QCString &explicitScopePart);
 371
 372 int computeQualifiedIndex(const QCString &name);
 373
 374 void addDirPrefix(QCString &fileName);
 375
 376 QCString relativePathToRoot(const char *name);
 377
 378 void createSubDirs(QDir &d);
 379
 380 QCString stripPath(const char *s);
 381
 382 bool containsWord(const QCString &s,const QCString &word);
 383
 384 bool findAndRemoveWord(QCString &s,const QCString &word);
 385
 386 QCString stripLeadingAndTrailingEmptyLines(const QCString &s,int &docLine);
 387
 388 //void stringToSearchIndex(const QCString &docUrlBase,const QCString &title,
 389 //                         const QCString &str, bool priority=FALSE,
 390 //                         const QCString &anchor="");
 391
 392 bool updateLanguageMapping(const QCString &extension,const QCString &parser);
 393 SrcLangExt getLanguageFromFileName(const QCString& fileName);
 394 void initDefaultExtensionMapping();
 395 void addCodeOnlyMappings();
 396
 397 MemberDef *getMemberFromSymbol(Definition *scope,FileDef *fileScope,
 398                                 const char *n);
 399 bool checkIfTypedef(Definition *scope,FileDef *fileScope,const char *n);
 400
 401 ClassDef *newResolveTypedef(const FileDef *fileScope,MemberDef *md,
 402                             MemberDef **pMemType=0,QCString *pTemplSpec=0,
 403                             QCString *pResolvedType=0,
 404                             ArgumentList *actTemplParams=0);
 405
 406 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QCString &doc,const QCString &fileName,int lineNr);
 407
 408 QCString transcodeCharacterStringToUTF8(const QCString &input);
 409
 410 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);
 411
 412 QCString extractAliasArgs(const QCString &args,int pos);
 413
 414 int countAliasArguments(const QCString argList);
 415
 416 //QCString replaceAliasArguments(const QCString &aliasValue,const QCString &argList);
 417
 418 QCString resolveAliasCmd(const QCString aliasCmd);
 419 QCString expandAlias(const QCString &aliasName,const QCString &aliasValue);
 420
 421 void writeTypeConstraints(OutputList &ol,Definition *d,ArgumentList *al);
 422
 423 QCString convertCharEntitiesToUTF8(const QCString &s);
 424
 425 void stackTrace();
 426
 427 bool readInputFile(const char *fileName,BufStr &inBuf,
 428                    bool filter=TRUE,bool isSourceCode=FALSE);
 429 QCString filterTitle(const QCString &title);
 430
 431 bool patternMatch(const QFileInfo &fi,const QStrList *patList);
 432
 433 QCString externalLinkTarget();
 434 QCString externalRef(const QCString &relPath,const QCString &ref,bool href);
 435 int nextUtf8CharPosition(const QCString &utf8Str,int len,int startPos);
 436 const char *writeUtf8Char(FTextStream &t,const char *s);
 437
 438
 439 /** Data associated with a HSV colored image. */
 440 struct ColoredImgDataItem
 441 {
 442   const char *name;
 443   unsigned short width;
 444   unsigned short height;
 445   unsigned char *content;
 446   unsigned char *alpha;
 447 };
 448
 449 void writeColoredImgData(const char *dir,ColoredImgDataItem data[]);
 450 QCString replaceColorMarkers(const char *str);
 451
 452 bool copyFile(const QCString &src,const QCString &dest);
 453 QCString extractBlock(const QCString text,const QCString marker);
 454 int lineBlock(const QCString text,const QCString marker);
 455
 456 QCString correctURL(const QCString &url,const QCString &relPath);
 457
 458 QCString processMarkup(const QCString &s);
 459
 460 bool protectionLevelVisible(Protection prot);
 461
 462 QCString stripIndentation(const QCString &s);
 463
 464 QCString getDotImageExtension(void);
 465
 466 bool fileVisibleInIndex(FileDef *fd,bool &genSourceFile);
 467
 468 void addDocCrossReference(MemberDef *src,MemberDef *dst);
 469
 470 uint getUtf8Code( const QCString& s, int idx );
 471 uint getUtf8CodeToLower( const QCString& s, int idx );
 472 uint getUtf8CodeToUpper( const QCString& s, int idx );
 473
 474 QCString extractDirection(QCString &docs);
 475
 476 void convertProtectionLevel(
 477                    MemberListType inListType,
 478                    Protection inProt,
 479                    int *outListType1,
 480                    int *outListType2
 481                   );
 482
 483 bool mainPageHasTitle();
 484 bool openOutputFile(const char *outFile,QFile &f);
 485 void writeExtraLatexPackages(FTextStream &t);
 486 void writeLatexSpecialFormulaChars(FTextStream &t);
 487
 488 int usedTableLevels();
 489 void incUsedTableLevels();
 490 void decUsedTableLevels();
 491
 492 #endif