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