src/util.h

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