1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 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 util.h 

    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 

    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 

    58 //--------------------------------------------------------------------

    59 

    60 class TextGeneratorIntf

    61 {

    62   public:

    63     virtual ~TextGeneratorIntf() {}

    64     virtual void writeString(const char *,bool) const = 0;

    65     virtual void writeBreak() const = 0;

    66     virtual void writeLink(const char *extRef,const char *file,

    67                       const char *anchor,const char *text

    68                      ) const = 0; 

    69 };

    70 

    71 class TextGeneratorOLImpl : public TextGeneratorIntf

    72 {

    73   public:

    74     virtual ~TextGeneratorOLImpl() {}

    75     TextGeneratorOLImpl(OutputDocInterface &od);

    76     void writeString(const char *s,bool keepSpaces) const;

    77     void writeBreak() const;

    78     void writeLink(const char *extRef,const char *file,

    79                    const char *anchor,const char *text

    80                   ) const;

    81   private:

    82     OutputDocInterface &m_od;

    83 };

    84 

    85 //--------------------------------------------------------------------

    86 

    87 enum SrcLangExt

    88 {

    89   SrcLangExt_IDL    = 0x0008,

    90   SrcLangExt_Java   = 0x0010,

    91   SrcLangExt_CSharp = 0x0020,

    92   SrcLangExt_D      = 0x0040,

    93   SrcLangExt_PHP    = 0x0080,

    94   SrcLangExt_ObjC   = 0x0100,

    95   SrcLangExt_Cpp    = 0x0200,

    96   SrcLangExt_JS     = 0x0400,

    97   SrcLangExt_Python = 0x0800,

    98   SrcLangExt_F90    = 0x1000,

    99   SrcLangExt_VHDL   = 0x2000,

   100   SrcLangExt_XML    = 0x4000

   101 };

   102 

   103 //--------------------------------------------------------------------

   104 

   105 void linkifyText(const TextGeneratorIntf &ol,

   106                  Definition *scope,

   107                  FileDef *fileScope,

   108                  const char *name,

   109                  const char *text,

   110                  bool autoBreak=FALSE,

   111                  bool external=TRUE,

   112                  bool keepSpaces=FALSE

   113                 );

   114 

   115 void setAnchors(ClassDef *cd,char id,MemberList *ml,int groupId=-1);

   116 

   117 QCString fileToString(const char *name,bool filter=FALSE);

   118 

   119 QCString dateToString(bool);

   120 

   121 bool getDefs(const QCString &scopeName,

   122                     const QCString &memberName, 

   123                     const char *, 

   124                     MemberDef *&md, 

   125                     ClassDef *&cd,

   126                     FileDef *&fd, 

   127                     NamespaceDef *&nd,

   128                     GroupDef *&gd,

   129                     bool forceEmptyScope=FALSE,

   130                     FileDef *currentFile=0,

   131                     bool checkCV=FALSE

   132                    );

   133 

   134 QCString getFileFilter(const char* name);

   135 

   136 bool resolveRef(/* in */  const char *scName,

   137                 /* in */  const char *name,

   138                 /* in */  bool inSeeBlock,

   139                 /* out */ Definition **resContext,

   140                 /* out */ MemberDef  **resMember,

   141                 /* in */  bool lookForSpecializations = TRUE,

   142                 /* in */  FileDef *currentFile = 0

   143                );

   144 

   145 bool resolveLink(/* in */  const char *scName,

   146                  /* in */  const char *lr,

   147                  /* in */  bool inSeeBlock,

   148                  /* out */ Definition **resContext,

   149                  /* out */ QCString &resAnchor

   150                 );

   151 

   152 bool generateRef(OutputDocInterface &od,const char *,

   153                         const char *,bool inSeeBlock,const char * =0);

   154 

   155 bool generateLink(OutputDocInterface &od,const char *,

   156                          const char *,bool inSeeBlock,const char *);

   157 

   158 void generateFileRef(OutputDocInterface &od,const char *,

   159                              const char *linkTxt=0);

   160 

   161 void writePageRef(OutputDocInterface &od,const char *cn,const char *mn);

   162 

   163 QCString getCanonicalTemplateSpec(Definition *d,FileDef *fs,const QCString& spec);

   164 

   165 bool matchArguments2(Definition *srcScope,FileDef *srcFileScope,ArgumentList *srcAl,

   166                      Definition *dstScope,FileDef *dstFileScope,ArgumentList *dstAl,

   167                      bool checkCV

   168                     );

   169 

   170 void mergeArguments(ArgumentList *,ArgumentList *,bool forceNameOverwrite=FALSE);

   171 

   172 QCString substituteClassNames(const QCString &s);

   173 

   174 QCString substitute(const char *s,const char *src,const char *dst);

   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   // PaulRo: This was return c=='_' || isalnum(c) || c>=128 || c<0;

   201   // but with negative numbers isalnum was called and this gave an

   202   // assertion error from istype.c

   203   return c=='_' || c>=128 || c<0 || isalnum(c);

   204 }

   205 

   206 QCString removeRedundantWhiteSpace(const QCString &s);

   207 

   208 QCString argListToString(ArgumentList *al,bool useCanonicalType=FALSE);

   209 

   210 QCString tempArgListToString(ArgumentList *al);

   211 

   212 QCString generateMarker(int id);

   213 

   214 void writeExample(OutputList &ol,ExampleSDict *el);

   215 

   216 QCString stripAnonymousNamespaceScope(const QCString &s);

   217 

   218 QCString stripFromPath(const QCString &path);

   219 

   220 QCString stripFromIncludePath(const QCString &path);

   221 

   222 bool rightScopeMatch(const QCString &scope, const QCString &name);

   223 

   224 bool leftScopeMatch(const QCString &scope, const QCString &name);

   225 

   226 QCString substituteKeywords(const QCString &s,const char *title,const QCString &relPath="");

   227 

   228 int getPrefixIndex(const QCString &name);

   229 

   230 QCString removeAnonymousScopes(const QCString &s);

   231 

   232 QCString replaceAnonymousScopes(const QCString &s,const char *replacement=0);

   233 

   234 void initClassHierarchy(ClassSDict *cl);

   235 

   236 bool hasVisibleRoot(BaseClassList *bcl);

   237 

   238 int minClassDistance(const ClassDef *cd,const ClassDef *bcd,int level=0);

   239 

   240 QCString convertNameToFile(const char *name,bool allowDots=FALSE);

   241 

   242 void extractNamespaceName(const QCString &scopeName,

   243                           QCString &className,QCString &namespaceName,

   244                           bool allowEmptyClass=FALSE);

   245 

   246 QCString insertTemplateSpecifierInScope(const QCString &scope,const QCString &templ);

   247 

   248 QCString stripScope(const char *name);

   249 

   250 QCString convertToHtml(const char *s,bool keepEntities=TRUE);

   251 

   252 QCString convertToXML(const char *s);

   253 

   254 QCString getOverloadDocs();

   255 

   256 void addMembersToMemberGroup(/* in */     MemberList *ml,

   257                              /* in,out */ MemberGroupSDict **ppMemberGroupSDict,

   258                              /* in */     Definition *context);

   259 

   260 int extractClassNameFromType(const QCString &type,int &pos,

   261                               QCString &name,QCString &templSpec);

   262 

   263 QCString substituteTemplateArgumentsInString(

   264        const QCString &name,

   265        ArgumentList *formalArgs,

   266        ArgumentList *actualArgs);

   267 

   268 ArgumentList *copyArgumentList(const ArgumentList *src);

   269 

   270 QList<ArgumentList> *copyArgumentLists(const QList<ArgumentList> *srcLists);

   271 

   272 QCString stripTemplateSpecifiersFromScope(const QCString &fullName,

   273                                           bool parentOnly=TRUE,

   274                                           QCString *lastScopeStripped=0);

   275 

   276 QCString resolveTypeDef(Definition *d,const QCString &name,

   277                         Definition **typedefContext=0);

   278 

   279 QCString mergeScopes(const QCString &leftScope,const QCString &rightScope);

   280 

   281 int getScopeFragment(const QCString &s,int p,int *l);

   282 

   283 int filterCRLF(char *buf,int len);

   284 

   285 void addRefItem(const QList<ListItemInfo> *sli,const char *prefix,

   286                 const char *key,

   287                 const char *name,const char *title,const char *args);

   288 

   289 PageDef *addRelatedPage(const char *name,const QCString &ptitle,

   290                            const QCString &doc,QList<SectionInfo> *anchors,

   291                            const char *fileName,int startLine,

   292                            const QList<ListItemInfo> *sli,

   293                            GroupDef *gd=0,

   294                            TagInfo *tagInfo=0

   295                           );

   296 

   297 QCString escapeCharsInString(const char *name,bool allowDots);

   298 

   299 void addGroupListToTitle(OutputList &ol,Definition *d);

   300 

   301 void filterLatexString(QTextStream &t,const char *str,

   302                        bool insideTabbing=FALSE,bool insidePre=FALSE,

   303                        bool insideItem=FALSE);

   304 

   305 QCString rtfFormatBmkStr(const char *name);

   306 

   307 QCString linkToText(const char *link,bool isFileName);

   308 

   309 QCString stripExtension(const char *fName);

   310 

   311 void replaceNamespaceAliases(QCString &scope,int i);

   312 

   313 int isAccessibleFrom(Definition *scope,FileDef *fileScope,Definition *item);

   314 

   315 int isAccessibleFromWithExpScope(Definition *scope,FileDef *fileScope,Definition *item,

   316                      const QCString &explicitScopePart);

   317 

   318 int computeQualifiedIndex(const QCString &name);

   319 

   320 void addDirPrefix(QCString &fileName);

   321 

   322 QCString relativePathToRoot(const char *name);

   323 

   324 void createSubDirs(QDir &d);

   325 

   326 QCString stripPath(const char *s);

   327 

   328 bool containsWord(const QCString &s,const QCString &word);

   329 

   330 bool findAndRemoveWord(QCString &s,const QCString &word);

   331 

   332 QCString stripLeadingAndTrailingEmptyLines(const QCString &s);

   333 

   334 //void stringToSearchIndex(const QCString &docUrlBase,const QCString &title,

   335 //                         const QCString &str, bool priority=FALSE,

   336 //                         const QCString &anchor="");

   337 

   338 bool updateLanguageMapping(const QCString &extension,const QCString &parser);

   339 SrcLangExt getLanguageFromFileName(const QCString fileName);

   340 void initDefaultExtensionMapping();

   341 

   342 bool checkIfTypedef(Definition *scope,FileDef *fileScope,const char *n);

   343 

   344 ClassDef *newResolveTypedef(FileDef *fileScope,MemberDef *md,

   345                             MemberDef **pMemType=0,QCString *pTemplSpec=0,

   346                             QCString *pResolvedType=0,

   347                             ArgumentList *actTemplParams=0);

   348 

   349 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QString &doc,const QCString &fileName,int lineNr);

   350 

   351 QCString transcodeCharacterStringToUTF8(const QCString &input);

   352 

   353 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);

   354 

   355 QCString extractAliasArgs(const QCString &args,int pos);

   356 

   357 int countAliasArguments(const QCString argList);

   358 

   359 QCString replaceAliasArguments(const QCString &aliasValue,const QCString &argList);

   360 

   361 QCString resolveAliasCmd(const QCString aliasCmd);

   362 QCString expandAlias(const QCString &aliasName,const QCString &aliasValue);

   363 

   364 void writeTypeConstraints(OutputList &ol,Definition *d,ArgumentList *al);

   365 

   366 QCString convertCharEntitiesToUTF8(const QCString &s);

   367 

   368 bool usingTreeIndex();

   369 void stackTrace();

   370 

   371 bool readInputFile(const char *fileName,BufStr &inBuf);

   372 QCString filterTitle(const QCString &title);

   373 

   374 

   375 #endif

   376