1 /******************************************************************************
2 *
3 * Copyright (C) 1997-2021 by Dimitri van Heesch.
4 *
5 * Permission to use, copy, modify, and distribute this software and its
6 * documentation under the terms of the GNU General Public License is hereby
7 * granted. No representations are made about the suitability of this software
8 * for any purpose. It is provided "as is" without express or implied warranty.
9 * See the GNU General Public License for more details.
10 *
11 * Documents produced by Doxygen are derivative works derived from the
12 * input used in their production; they are not affected by this license.
13 *
14 */
15
16 #ifndef UTIL_H
17 #define UTIL_H
18
19 /*! \file
20 * \brief A bunch of utility functions.
21 */
22
23 #include <memory>
24 #include <unordered_map>
25 #include <algorithm>
26 #include <functional>
27 #include <fstream>
28
29 #include <ctype.h>
30 #include "types.h"
31 #include "docparser.h"
32 #include "containers.h"
33 #include "outputgen.h"
34 #include "regex.h"
35 #include "conceptdef.h"
36
37 //--------------------------------------------------------------------
38
39 class ClassDef;
40 class FileDef;
41 class MemberList;
42 class NamespaceDef;
43 class FileNameLinkedMap;
44 class ArgumentList;
45 class OutputList;
46 class OutputDocInterface;
47 class MemberDef;
48 class GroupDef;
49 struct TagInfo;
50 class PageDef;
51 class SectionInfo;
52 class Definition;
53 class BufStr;
54 class FileInfo;
55 class Dir;
56
57 //--------------------------------------------------------------------
58
59 /** Abstract interface for a hyperlinked text fragment. */
60 class TextGeneratorIntf
61 {
62 public:
~TextGeneratorIntf()63 virtual ~TextGeneratorIntf() {}
64 virtual void writeString(const QCString &,bool) const = 0;
65 virtual void writeBreak(int indent) const = 0;
66 virtual void writeLink(const QCString &extRef,const QCString &file,
67 const QCString &anchor,const QCString &text
68 ) const = 0;
69 };
70
71 /** Implements TextGeneratorIntf for an OutputDocInterface stream. */
72 class TextGeneratorOLImpl : public TextGeneratorIntf
73 {
74 public:
~TextGeneratorOLImpl()75 virtual ~TextGeneratorOLImpl() {}
76 TextGeneratorOLImpl(OutputDocInterface &od);
77 void writeString(const QCString &s,bool keepSpaces) const;
78 void writeBreak(int indent) const;
79 void writeLink(const QCString &extRef,const QCString &file,
80 const QCString &anchor,const QCString &text
81 ) const;
82 private:
83 OutputDocInterface &m_od;
84 };
85
86 //--------------------------------------------------------------------
87
88 QCString langToString(SrcLangExt lang);
89 QCString getLanguageSpecificSeparator(SrcLangExt lang,bool classScope=FALSE);
90
91 //--------------------------------------------------------------------
92
93 void linkifyText(const TextGeneratorIntf &ol,
94 const Definition *scope,
95 const FileDef *fileScope,
96 const Definition *self,
97 const QCString &text,
98 bool autoBreak=FALSE,
99 bool external=TRUE,
100 bool keepSpaces=FALSE,
101 int indentLevel=0
102 );
103
104 QCString fileToString(const QCString &name,bool filter=FALSE,bool isSourceCode=FALSE);
105
106 QCString dateToString(bool);
107
108 bool getDefs(const QCString &scopeName,
109 const QCString &memberName,
110 const QCString &args,
111 const MemberDef *&md,
112 const ClassDef *&cd,
113 const FileDef *&fd,
114 const NamespaceDef *&nd,
115 const GroupDef *&gd,
116 bool forceEmptyScope=FALSE,
117 const FileDef *currentFile=0,
118 bool checkCV=FALSE
119 );
120
121 QCString getFileFilter(const QCString &name,bool isSourceCode);
122
123 bool resolveRef(/* in */ const QCString &scName,
124 /* in */ const QCString &name,
125 /* in */ bool inSeeBlock,
126 /* out */ const Definition **resContext,
127 /* out */ const MemberDef **resMember,
128 /* in */ bool lookForSpecializations = TRUE,
129 /* in */ const FileDef *currentFile = 0,
130 /* in */ bool checkScope = FALSE
131 );
132
133 bool resolveLink(/* in */ const QCString &scName,
134 /* in */ const QCString &lr,
135 /* in */ bool inSeeBlock,
136 /* out */ const Definition **resContext,
137 /* out */ QCString &resAnchor
138 );
139
140 bool generateLink(OutputDocInterface &od,const QCString &,
141 const QCString &,bool inSeeBlock,const QCString &);
142
143 void generateFileRef(OutputDocInterface &od,const QCString &,
144 const QCString &linkTxt=QCString());
145
146 void writePageRef(OutputDocInterface &od,const QCString &cn,const QCString &mn);
147
148 QCString getCanonicalTemplateSpec(const Definition *d,const FileDef *fs,const QCString& spec);
149
150 bool matchArguments2(const Definition *srcScope,const FileDef *srcFileScope,const ArgumentList *srcAl,
151 const Definition *dstScope,const FileDef *dstFileScope,const ArgumentList *dstAl,
152 bool checkCV
153 );
154
155 void mergeArguments(ArgumentList &,ArgumentList &,bool forceNameOverwrite=FALSE);
156
157 QCString substituteClassNames(const QCString &s);
158
159
160 QCString clearBlock(const char *s,const char *begin,const char *end);
161 QCString selectBlock(const QCString& s,const QCString &name,bool enable, OutputGenerator::OutputType o);
162 QCString removeEmptyLines(const QCString &s);
163
164
165 FileDef *findFileDef(const FileNameLinkedMap *fnMap,const QCString &n,
166 bool &ambig);
167
168 QCString showFileDefMatches(const FileNameLinkedMap *fnMap,const QCString &n);
169
170 int guessSection(const QCString &name);
171
isId(int c)172 inline bool isId(int c)
173 {
174 return c=='_' || c>=128 || c<0 || isalnum(c) || c=='$';
175 }
isIdJS(int c)176 inline bool isIdJS(int c)
177 {
178 return c>=128 || c<0 || isalnum(c);
179 }
180
181 QCString removeRedundantWhiteSpace(const QCString &s);
182
183 QCString argListToString(const ArgumentList &al,bool useCanonicalType=FALSE,bool showDefVals=TRUE);
184
185 QCString tempArgListToString(const ArgumentList &al,SrcLangExt lang,bool includeDefaults=true);
186
187 QCString generateMarker(int id);
188
189 void writeExamples(OutputList &ol,const ExampleList &el);
190
191 QCString stripAnonymousNamespaceScope(const QCString &s);
192
193 QCString stripFromPath(const QCString &path);
194
195 QCString stripFromIncludePath(const QCString &path);
196
197 bool rightScopeMatch(const QCString &scope, const QCString &name);
198
199 bool leftScopeMatch(const QCString &scope, const QCString &name);
200
201 QCString substituteKeywords(const QCString &s,const QCString &title,
202 const QCString &projName,const QCString &projNum,const QCString &projBrief);
203
204 int getPrefixIndex(const QCString &name);
205
206 QCString removeAnonymousScopes(const QCString &s);
207
208 QCString replaceAnonymousScopes(const QCString &s,const QCString &replacement=QCString());
209
210 QCString convertNameToFile(const QCString &name,bool allowDots=FALSE,bool allowUnderscore=FALSE);
211
212 void extractNamespaceName(const QCString &scopeName,
213 QCString &className,QCString &namespaceName,
214 bool allowEmptyClass=FALSE);
215
216 QCString insertTemplateSpecifierInScope(const QCString &scope,const QCString &templ);
217
218 QCString stripScope(const QCString &name);
219
220 QCString convertToId(const QCString &s);
221 QCString correctId(const QCString &s);
222
223 QCString convertToHtml(const QCString &s,bool keepEntities=TRUE);
224
225 QCString convertToLaTeX(const QCString &s,bool insideTabbing=FALSE,bool keepSpaces=FALSE);
226
227 QCString convertToXML(const QCString &s, bool keepEntities=FALSE);
228
229 QCString convertToDocBook(const QCString &s, const bool retainNewline = false);
230
231 QCString convertToJSString(const QCString &s);
232
233 QCString convertToPSString(const QCString &s);
234
235 QCString getOverloadDocs();
236
237 void addMembersToMemberGroup(/* in,out */ MemberList *ml,
238 /* in,out */ MemberGroupList *pMemberGroups,
239 /* in */ const Definition *context);
240
241 int extractClassNameFromType(const QCString &type,int &pos,
242 QCString &name,QCString &templSpec,SrcLangExt=SrcLangExt_Unknown);
243
244 QCString normalizeNonTemplateArgumentsInString(
245 const QCString &name,
246 const Definition *context,
247 const ArgumentList &formalArgs);
248
249 QCString substituteTemplateArgumentsInString(
250 const QCString &name,
251 const ArgumentList &formalArgs,
252 const std::unique_ptr<ArgumentList> &actualArgs);
253
254 QCString stripTemplateSpecifiersFromScope(const QCString &fullName,
255 bool parentOnly=TRUE,
256 QCString *lastScopeStripped=0);
257
258 QCString resolveTypeDef(const Definition *d,const QCString &name,
259 const Definition **typedefContext=0);
260
261 QCString mergeScopes(const QCString &leftScope,const QCString &rightScope);
262
263 int getScopeFragment(const QCString &s,int p,int *l);
264
265 void addRefItem(const RefItemVector &sli,
266 const QCString &key,
267 const QCString &prefix,
268 const QCString &name,
269 const QCString &title,
270 const QCString &args,
271 const Definition *scope);
272
273 PageDef *addRelatedPage(const QCString &name,
274 const QCString &ptitle,
275 const QCString &doc,
276 const QCString &fileName,
277 int docLine,
278 int startLine,
279 const RefItemVector &sli = RefItemVector(),
280 GroupDef *gd=0,
281 const TagInfo *tagInfo=0,
282 bool xref=FALSE,
283 SrcLangExt lang=SrcLangExt_Unknown
284 );
285
286 QCString escapeCharsInString(const QCString &name,bool allowDots,bool allowUnderscore=FALSE);
287 QCString unescapeCharsInString(const QCString &s);
288
289 void addGroupListToTitle(OutputList &ol,const Definition *d);
290
291 void filterLatexString(TextStream &t,const QCString &str,
292 bool insideTabbing,
293 bool insidePre,
294 bool insideItem,
295 bool insideTable,
296 bool keepSpaces,
297 const bool retainNewline = false);
298
299 QCString latexEscapeLabelName(const QCString &s);
300 QCString latexEscapeIndexChars(const QCString &s);
301 QCString latexEscapePDFString(const QCString &s);
302 QCString latexFilterURL(const QCString &s);
303
304 QCString rtfFormatBmkStr(const QCString &name);
305
306 QCString linkToText(SrcLangExt lang,const QCString &link,bool isFileName);
307
308 bool checkExtension(const QCString &fName, const QCString &ext);
309
310 QCString addHtmlExtensionIfMissing(const QCString &fName);
311
312 QCString stripExtensionGeneral(const QCString &fName, const QCString &ext);
313
314 QCString stripExtension(const QCString &fName);
315
316 void replaceNamespaceAliases(QCString &scope,int i);
317
318 int computeQualifiedIndex(const QCString &name);
319
320 void addDirPrefix(QCString &fileName);
321
322 QCString relativePathToRoot(const QCString &name);
323
324 void createSubDirs(const Dir &d);
325 void clearSubDirs(const Dir &d);
326
327 QCString stripPath(const QCString &s);
328
329 bool containsWord(const QCString &s,const char *word);
330
331 bool findAndRemoveWord(QCString &s,const char *word);
332
333 QCString stripLeadingAndTrailingEmptyLines(const QCString &s,int &docLine);
334
335 bool updateLanguageMapping(const QCString &extension,const QCString &parser);
336 SrcLangExt getLanguageFromFileName(const QCString& fileName, SrcLangExt defLang=SrcLangExt_Cpp);
337 SrcLangExt getLanguageFromCodeLang(QCString &fileName);
338 QCString getFileNameExtension(const QCString &fn);
339 void initDefaultExtensionMapping();
340 void addCodeOnlyMappings();
341
342 bool checkIfTypedef(const Definition *scope,const FileDef *fileScope,const QCString &n);
343
344 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QCString &doc,const QCString &fileName,int lineNr);
345
346 QCString transcodeCharacterStringToUTF8(const QCString &input);
347
348 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);
349
350 QCString extractAliasArgs(const QCString &args,size_t pos);
351
352 int countAliasArguments(const QCString &argList);
353
354 QCString resolveAliasCmd(const QCString &aliasCmd);
355 std::string expandAlias(const std::string &aliasName,const std::string &aliasValue);
356
357 void writeTypeConstraints(OutputList &ol,const Definition *d,const ArgumentList &al);
358
359 QCString convertCharEntitiesToUTF8(const QCString &s);
360
361 void stackTrace();
362
363 bool readInputFile(const QCString &fileName,BufStr &inBuf,
364 bool filter=TRUE,bool isSourceCode=FALSE);
365 QCString filterTitle(const QCString &title);
366
367 bool patternMatch(const FileInfo &fi,const StringVector &patList);
368
369 QCString externalLinkTarget(const bool parent = false);
370 QCString externalRef(const QCString &relPath,const QCString &ref,bool href);
371 int nextUtf8CharPosition(const QCString &utf8Str,uint len,uint startPos);
372
373 void writeMarkerList(OutputList &ol,const std::string &markerText,size_t numMarkers,
374 std::function<void(size_t)> replaceFunc);
375
376 /** Data associated with a HSV colored image. */
377 struct ColoredImgDataItem
378 {
379 const char *name;
380 unsigned short width;
381 unsigned short height;
382 unsigned char *content;
383 unsigned char *alpha;
384 };
385
386 void writeColoredImgData(const QCString &dir,ColoredImgDataItem data[]);
387 QCString replaceColorMarkers(const QCString &str);
388
389 bool copyFile(const QCString &src,const QCString &dest);
390 QCString extractBlock(const QCString &text,const QCString &marker);
391 int lineBlock(const QCString &text,const QCString &marker);
392
393 bool isURL(const QCString &url);
394
395 QCString correctURL(const QCString &url,const QCString &relPath);
396
397 QCString processMarkup(const QCString &s);
398
399 bool protectionLevelVisible(Protection prot);
400
401 QCString stripIndentation(const QCString &s);
402 void stripIndentation(QCString &doc,const int indentationLevel);
403
404 QCString getDotImageExtension();
405
406 bool fileVisibleInIndex(const FileDef *fd,bool &genSourceFile);
407
408 QCString extractDirection(QCString &docs);
409
410 void convertProtectionLevel(
411 MemberListType inListType,
412 Protection inProt,
413 int *outListType1,
414 int *outListType2
415 );
416
417 bool mainPageHasTitle();
418 bool openOutputFile(const QCString &outFile,std::ofstream &f);
419 void writeExtraLatexPackages(TextStream &t);
420 void writeLatexSpecialFormulaChars(TextStream &t);
421
422 StringVector split(const std::string &s,const std::string &delimiter);
423 StringVector split(const std::string &s,const reg::Ex &delimiter);
424 int findIndex(const StringVector &sv,const std::string &s);
425 int findIndex(const std::string &s,const reg::Ex &re);
426 std::string join(const StringVector &s,const std::string &delimiter);
427
428 bool recognizeFixedForm(const QCString &contents, FortranFormat format);
429 FortranFormat convertFileNameFortranParserCode(QCString fn);
430
431 QCString integerToAlpha(int n, bool upper=true);
432 QCString integerToRoman(int n, bool upper=true);
433
434 #endif
435