1 /******************************************************************************
5 * Copyright (C) 1997-2014 by Dimitri van Heesch.
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.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
22 * \brief A bunch of utility functions.
29 #include "docparser.h"
31 //--------------------------------------------------------------------
40 class OutputDocInterface;
48 class MemberGroupSDict;
50 class MemberNameInfoSDict;
61 //--------------------------------------------------------------------
63 /** Abstract interface for a hyperlinked text fragment. */
64 class TextGeneratorIntf
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
75 /** Implements TextGeneratorIntf for an OutputDocInterface stream. */
76 class TextGeneratorOLImpl : public TextGeneratorIntf
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
87 OutputDocInterface &m_od;
90 //--------------------------------------------------------------------
92 /** @brief maps a unicode character code to a list of T::ElementType's
95 class LetterToIndexMap : public SIntDict<T>
98 LetterToIndexMap() { SIntDict<T>::setAutoDelete(TRUE); }
99 void append(uint letter,typename T::ElementType *elem)
101 T *l = SIntDict<T>::find((int)letter);
105 SIntDict<T>::inSort((int)letter,l);
110 int compareValues(const T *l1, const T *l2) const
112 return (int)l1->letter()-(int)l2->letter();
116 //--------------------------------------------------------------------
118 QCString langToString(SrcLangExt lang);
119 QCString getLanguageSpecificSeparator(SrcLangExt lang,bool classScope=FALSE);
121 //--------------------------------------------------------------------
123 void linkifyText(const TextGeneratorIntf &ol,
128 bool autoBreak=FALSE,
130 bool keepSpaces=FALSE,
134 void setAnchors(MemberList *ml);
136 QCString fileToString(const char *name,bool filter=FALSE,bool isSourceCode=FALSE);
138 QCString dateToString(bool);
140 bool getDefs(const QCString &scopeName,
141 const QCString &memberName,
148 bool forceEmptyScope=FALSE,
149 FileDef *currentFile=0,
151 const char *forceTagFile=0
154 QCString getFileFilter(const char* name,bool isSourceCode);
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
166 bool resolveLink(/* in */ const char *scName,
167 /* in */ const char *lr,
168 /* in */ bool inSeeBlock,
169 /* out */ Definition **resContext,
170 /* out */ QCString &resAnchor
173 //bool generateRef(OutputDocInterface &od,const char *,
174 // const char *,bool inSeeBlock,const char * =0);
176 bool generateLink(OutputDocInterface &od,const char *,
177 const char *,bool inSeeBlock,const char *);
179 void generateFileRef(OutputDocInterface &od,const char *,
180 const char *linkTxt=0);
182 void writePageRef(OutputDocInterface &od,const char *cn,const char *mn);
184 QCString getCanonicalTemplateSpec(Definition *d,FileDef *fs,const QCString& spec);
186 bool matchArguments2(Definition *srcScope,FileDef *srcFileScope,ArgumentList *srcAl,
187 Definition *dstScope,FileDef *dstFileScope,ArgumentList *dstAl,
191 void mergeArguments(ArgumentList *,ArgumentList *,bool forceNameOverwrite=FALSE);
193 QCString substituteClassNames(const QCString &s);
195 QCString substitute(const char *s,const char *src,const char *dst);
197 QCString clearBlock(const char *s,const char *begin,const char *end);
199 QCString selectBlock(const QCString& s,const QCString &name,bool which);
201 QCString resolveDefines(const char *n);
203 ClassDef *getClass(const char *key);
205 ClassDef *getResolvedClass(Definition *scope,
208 MemberDef **pTypeDef=0,
209 QCString *pTemplSpec=0,
210 bool mayBeUnlinkable=FALSE,
211 bool mayBeHidden=FALSE,
212 QCString *pResolvedType=0);
214 NamespaceDef *getResolvedNamespace(const char *key);
216 FileDef *findFileDef(const FileNameDict *fnDict,const char *n,
219 QCString showFileDefMatches(const FileNameDict *fnDict,const char *n);
221 int guessSection(const char *name);
223 inline bool isId(int c)
225 return c=='_' || c>=128 || c<0 || isalnum(c);
228 QCString removeRedundantWhiteSpace(const QCString &s);
230 QCString argListToString(ArgumentList *al,bool useCanonicalType=FALSE,bool showDefVals=TRUE);
232 QCString tempArgListToString(ArgumentList *al);
234 QCString generateMarker(int id);
236 void writeExample(OutputList &ol,ExampleSDict *el);
238 QCString stripAnonymousNamespaceScope(const QCString &s);
240 QCString stripFromPath(const QCString &path);
242 QCString stripFromIncludePath(const QCString &path);
244 bool rightScopeMatch(const QCString &scope, const QCString &name);
246 bool leftScopeMatch(const QCString &scope, const QCString &name);
248 QCString substituteKeywords(const QCString &s,const char *title,
249 const char *projName,const char *projNum,const char *projBrief);
251 int getPrefixIndex(const QCString &name);
253 QCString removeAnonymousScopes(const QCString &s);
255 QCString replaceAnonymousScopes(const QCString &s,const char *replacement=0);
257 void initClassHierarchy(ClassSDict *cl);
259 bool hasVisibleRoot(BaseClassList *bcl);
260 bool classHasVisibleChildren(ClassDef *cd);
261 bool namespaceHasVisibleChild(NamespaceDef *nd,bool includeClasses);
262 bool classVisibleInIndex(ClassDef *cd);
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);
267 QCString convertNameToFile(const char *name,bool allowDots=FALSE,bool allowUnderscore=FALSE);
269 void extractNamespaceName(const QCString &scopeName,
270 QCString &className,QCString &namespaceName,
271 bool allowEmptyClass=FALSE);
273 QCString insertTemplateSpecifierInScope(const QCString &scope,const QCString &templ);
275 QCString stripScope(const char *name);
277 QCString convertToHtml(const char *s,bool keepEntities=TRUE);
279 QCString convertToXML(const char *s);
281 QCString convertToJSString(const char *s);
283 QCString getOverloadDocs();
285 void addMembersToMemberGroup(/* in */ MemberList *ml,
286 /* in,out */ MemberGroupSDict **ppMemberGroupSDict,
287 /* in */ Definition *context);
289 int extractClassNameFromType(const QCString &type,int &pos,
290 QCString &name,QCString &templSpec,SrcLangExt=SrcLangExt_Unknown);
292 QCString normalizeNonTemplateArgumentsInString(
293 const QCString &name,
295 const ArgumentList *formalArgs);
297 QCString substituteTemplateArgumentsInString(
298 const QCString &name,
299 ArgumentList *formalArgs,
300 ArgumentList *actualArgs);
302 QList<ArgumentList> *copyArgumentLists(const QList<ArgumentList> *srcLists);
304 QCString stripTemplateSpecifiersFromScope(const QCString &fullName,
305 bool parentOnly=TRUE,
306 QCString *lastScopeStripped=0);
308 QCString resolveTypeDef(Definition *d,const QCString &name,
309 Definition **typedefContext=0);
311 QCString mergeScopes(const QCString &leftScope,const QCString &rightScope);
313 int getScopeFragment(const QCString &s,int p,int *l);
315 int filterCRLF(char *buf,int len);
317 void addRefItem(const QList<ListItemInfo> *sli,const char *prefix,
319 const char *name,const char *title,const char *args);
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,
327 SrcLangExt lang=SrcLangExt_Unknown
330 QCString escapeCharsInString(const char *name,bool allowDots,bool allowUnderscore=FALSE);
332 void addGroupListToTitle(OutputList &ol,Definition *d);
334 void filterLatexString(FTextStream &t,const char *str,
335 bool insideTabbing=FALSE,
336 bool insidePre=FALSE,
337 bool insideItem=FALSE);
339 QCString rtfFormatBmkStr(const char *name);
341 QCString linkToText(SrcLangExt lang,const char *link,bool isFileName);
343 QCString stripExtension(const char *fName);
345 void replaceNamespaceAliases(QCString &scope,int i);
347 int isAccessibleFrom(Definition *scope,FileDef *fileScope,Definition *item);
349 int isAccessibleFromWithExpScope(Definition *scope,FileDef *fileScope,Definition *item,
350 const QCString &explicitScopePart);
352 int computeQualifiedIndex(const QCString &name);
354 void addDirPrefix(QCString &fileName);
356 QCString relativePathToRoot(const char *name);
358 void createSubDirs(QDir &d);
360 QCString stripPath(const char *s);
362 bool containsWord(const QCString &s,const QCString &word);
364 bool findAndRemoveWord(QCString &s,const QCString &word);
366 QCString stripLeadingAndTrailingEmptyLines(const QCString &s,int &docLine);
368 //void stringToSearchIndex(const QCString &docUrlBase,const QCString &title,
369 // const QCString &str, bool priority=FALSE,
370 // const QCString &anchor="");
372 bool updateLanguageMapping(const QCString &extension,const QCString &parser);
373 SrcLangExt getLanguageFromFileName(const QCString fileName);
374 void initDefaultExtensionMapping();
376 MemberDef *getMemberFromSymbol(Definition *scope,FileDef *fileScope,
378 bool checkIfTypedef(Definition *scope,FileDef *fileScope,const char *n);
380 ClassDef *newResolveTypedef(FileDef *fileScope,MemberDef *md,
381 MemberDef **pMemType=0,QCString *pTemplSpec=0,
382 QCString *pResolvedType=0,
383 ArgumentList *actTemplParams=0);
385 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QCString &doc,const QCString &fileName,int lineNr);
387 QCString transcodeCharacterStringToUTF8(const QCString &input);
389 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);
391 QCString extractAliasArgs(const QCString &args,int pos);
393 int countAliasArguments(const QCString argList);
395 //QCString replaceAliasArguments(const QCString &aliasValue,const QCString &argList);
397 QCString resolveAliasCmd(const QCString aliasCmd);
398 QCString expandAlias(const QCString &aliasName,const QCString &aliasValue);
400 void writeTypeConstraints(OutputList &ol,Definition *d,ArgumentList *al);
402 QCString convertCharEntitiesToUTF8(const QCString &s);
406 bool readInputFile(const char *fileName,BufStr &inBuf,
407 bool filter=TRUE,bool isSourceCode=FALSE);
408 QCString filterTitle(const QCString &title);
410 bool patternMatch(const QFileInfo &fi,const QStrList *patList);
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);
418 /** Data associated with a HSV colored image. */
419 struct ColoredImgDataItem
422 unsigned short width;
423 unsigned short height;
424 unsigned char *content;
425 unsigned char *alpha;
428 void writeColoredImgData(const char *dir,ColoredImgDataItem data[]);
429 QCString replaceColorMarkers(const char *str);
431 bool copyFile(const QCString &src,const QCString &dest);
432 QCString extractBlock(const QCString text,const QCString marker);
434 QCString correctURL(const QCString &url,const QCString &relPath);
436 QCString processMarkup(const QCString &s);
438 bool protectionLevelVisible(Protection prot);
440 QCString stripIndentation(const QCString &s);
442 bool fileVisibleInIndex(FileDef *fd,bool &genSourceFile);
444 void addDocCrossReference(MemberDef *src,MemberDef *dst);
446 uint getUtf8Code( const QCString& s, int idx );
447 uint getUtf8CodeToLower( const QCString& s, int idx );
448 uint getUtf8CodeToUpper( const QCString& s, int idx );
450 QCString extractDirection(QCString &docs);
452 void convertProtectionLevel(
453 MemberListType inListType,