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