doxygen
util.h
Go to the documentation of this file.
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 
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 
61 {
62  public:
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 
73 {
74  public:
75  virtual ~TextGeneratorOLImpl() {}
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 
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 
172 inline bool isId(int c)
173 {
174  return c=='_' || c>=128 || c<0 || isalnum(c) || c=='$';
175 }
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 
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 
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 
230 
231 QCString convertToJSString(const QCString &s);
232 
233 QCString convertToPSString(const QCString &s);
234 
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 
250  const QCString &name,
251  const ArgumentList &formalArgs,
252  const std::unique_ptr<ArgumentList> &actualArgs);
253 
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 
298 QCString latexEscapeLabelName(const QCString &s);
299 QCString latexEscapeIndexChars(const QCString &s);
300 QCString latexEscapePDFString(const QCString &s);
301 QCString latexFilterURL(const QCString &s);
302 
303 QCString rtfFormatBmkStr(const QCString &name);
304 
305 QCString linkToText(SrcLangExt lang,const QCString &link,bool isFileName);
306 
307 bool checkExtension(const QCString &fName, const QCString &ext);
308 
309 QCString addHtmlExtensionIfMissing(const QCString &fName);
310 
311 QCString stripExtensionGeneral(const QCString &fName, const QCString &ext);
312 
313 QCString stripExtension(const QCString &fName);
314 
315 void replaceNamespaceAliases(QCString &scope,int i);
316 
317 int computeQualifiedIndex(const QCString &name);
318 
319 void addDirPrefix(QCString &fileName);
320 
321 QCString relativePathToRoot(const QCString &name);
322 
323 void createSubDirs(const Dir &d);
324 void clearSubDirs(const Dir &d);
325 
326 QCString stripPath(const QCString &s);
327 
328 bool containsWord(const QCString &s,const char *word);
329 
330 bool findAndRemoveWord(QCString &s,const char *word);
331 
333 
334 bool updateLanguageMapping(const QCString &extension,const QCString &parser);
335 SrcLangExt getLanguageFromFileName(const QCString& fileName, SrcLangExt defLang=SrcLangExt_Cpp);
337 QCString getFileNameExtension(const QCString &fn);
338 void initDefaultExtensionMapping();
339 void addCodeOnlyMappings();
340 
341 bool checkIfTypedef(const Definition *scope,const FileDef *fileScope,const QCString &n);
342 
343 QCString parseCommentAsText(const Definition *scope,const MemberDef *member,const QCString &doc,const QCString &fileName,int lineNr);
344 
345 QCString transcodeCharacterStringToUTF8(const QCString &input);
346 
347 QCString recodeString(const QCString &str,const char *fromEncoding,const char *toEncoding);
348 
349 QCString extractAliasArgs(const QCString &args,size_t pos);
350 
351 int countAliasArguments(const QCString &argList);
352 
353 QCString resolveAliasCmd(const QCString &aliasCmd);
354 std::string expandAlias(const std::string &aliasName,const std::string &aliasValue);
355 
356 void writeTypeConstraints(OutputList &ol,const Definition *d,const ArgumentList &al);
357 
358 QCString convertCharEntitiesToUTF8(const QCString &s);
359 
360 void stackTrace();
361 
362 bool readInputFile(const QCString &fileName,BufStr &inBuf,
363  bool filter=TRUE,bool isSourceCode=FALSE);
364 QCString filterTitle(const QCString &title);
365 
366 bool patternMatch(const FileInfo &fi,const StringVector &patList);
367 
368 QCString externalLinkTarget(const bool parent = false);
369 QCString externalRef(const QCString &relPath,const QCString &ref,bool href);
370 int nextUtf8CharPosition(const QCString &utf8Str,uint len,uint startPos);
371 
372 void writeMarkerList(OutputList &ol,const std::string &markerText,size_t numMarkers,
373  std::function<void(size_t)> replaceFunc);
374 
377 {
378  const char *name;
379  unsigned short width;
380  unsigned short height;
381  unsigned char *content;
382  unsigned char *alpha;
383 };
384 
385 void writeColoredImgData(const QCString &dir,ColoredImgDataItem data[]);
387 
388 bool copyFile(const QCString &src,const QCString &dest);
389 QCString extractBlock(const QCString &text,const QCString &marker);
390 int lineBlock(const QCString &text,const QCString &marker);
391 
392 bool isURL(const QCString &url);
393 
394 QCString correctURL(const QCString &url,const QCString &relPath);
395 
396 QCString processMarkup(const QCString &s);
397 
398 bool protectionLevelVisible(Protection prot);
399 
400 QCString stripIndentation(const QCString &s);
401 void stripIndentation(QCString &doc,const int indentationLevel);
402 
403 QCString getDotImageExtension();
404 
405 bool fileVisibleInIndex(const FileDef *fd,bool &genSourceFile);
406 
408 
410  MemberListType inListType,
411  Protection inProt,
412  int *outListType1,
413  int *outListType2
414  );
415 
416 bool mainPageHasTitle();
417 bool openOutputFile(const QCString &outFile,std::ofstream &f);
418 void writeExtraLatexPackages(TextStream &t);
419 void writeLatexSpecialFormulaChars(TextStream &t);
420 
421 StringVector split(const std::string &s,const std::string &delimiter);
422 StringVector split(const std::string &s,const reg::Ex &delimiter);
423 int findIndex(const StringVector &sv,const std::string &s);
424 int findIndex(const std::string &s,const reg::Ex &re);
425 std::string join(const StringVector &s,const std::string &delimiter);
426 
427 bool recognizeFixedForm(const QCString &contents, FortranFormat format);
428 FortranFormat convertFileNameFortranParserCode(QCString fn);
429 
430 QCString integerToAlpha(int n, bool upper=true);
431 QCString integerToRoman(int n, bool upper=true);
432 
433 #endif
QCString convertToDocBook(const QCString &s)
Definition: util.cpp:3999
This class represents an function or template argument list.
Definition: arguments.h:59
This file contains a number of basic enums and types.
Definition: example.h:36
The common base class of all entity definitions found in the sources.
Definition: definition.h:76
An abstract interface of a namespace symbol.
Definition: namespacedef.h:54
A model of a class/file/namespace member symbol.
Definition: memberdef.h:45
void extractNamespaceName(const QCString &scopeName, QCString &className, QCString &namespaceName, bool allowEmptyClass=FALSE)
Definition: util.cpp:3733
QCString stripLeadingAndTrailingEmptyLines(const QCString &s, int &docLine)
Special version of QCString::stripWhiteSpace() that only strips completely blank lines.
Definition: util.cpp:5394
QCString stripTemplateSpecifiersFromScope(const QCString &fullName, bool parentOnly=TRUE, QCString *lastScopeStripped=0)
Definition: util.cpp:4605
QCString replaceColorMarkers(const QCString &str)
Replaces any markers of the form ##AA in input string str by new markers of the form #AABBCC...
Definition: util.cpp:6387
QCString langToString(SrcLangExt lang)
Returns a string representation of lang.
Definition: util.cpp:6519
Text streaming class that buffers data.
Definition: textstream.h:33
Interface used for generating documentation.
Definition: outputgen.h:527
A model of a file symbol.
Definition: filedef.h:73
This struct is used to capture the tag file information for an Entry.
Definition: entry.h:48
bool getDefs(const QCString &scopeName, const QCString &memberName, const QCString &args, const MemberDef *&md, const ClassDef *&cd, const FileDef *&fd, const NamespaceDef *&nd, const GroupDef *&gd, bool forceEmptyScope=FALSE, const FileDef *currentFile=0, bool checkCV=FALSE)
Definition: util.cpp:2208
SrcLangExt
Language as given by extension.
Definition: types.h:41
QCString fileToString(const QCString &name, bool filter=FALSE, bool isSourceCode=FALSE)
Definition: util.cpp:1394
QCString convertNameToFile(const QCString &name, bool allowDots=FALSE, bool allowUnderscore=FALSE)
Definition: util.cpp:3604
QCString stripFromPath(const QCString &path)
Definition: util.cpp:314
Definition: membergroup.h:109
Abstract interface for a hyperlinked text fragment.
Definition: util.h:60
void writeColoredImgData(const QCString &dir, ColoredImgDataItem data[])
Writes the intensity only bitmap represented by data as an image to directory dir using the colors de...
Definition: util.cpp:6363
QCString extractBlock(const QCString &text, const QCString &marker)
Returns the section of text, in between a pair of markers.
Definition: util.cpp:6453
QCString generateMarker(int id)
Definition: util.cpp:284
QCString mergeScopes(const QCString &leftScope, const QCString &rightScope)
Definition: util.cpp:4667
QCString stripFromIncludePath(const QCString &path)
Definition: util.cpp:322
QCString stripScope(const QCString &name)
Definition: util.cpp:3815
bool copyFile(const QCString &src, const QCString &dest)
Copies the contents of file with name src to the newly created file with name dest.
Definition: util.cpp:6439
StringVector split(const std::string &s, const std::string &delimiter)
split input string s by string delimiter delimiter. returns a vector of non-empty strings that are be...
Definition: util.cpp:7283
bool readInputFile(const QCString &fileName, BufStr &inBuf, bool filter=TRUE, bool isSourceCode=FALSE)
read a file name fileName and optionally filter and transcode it
Definition: util.cpp:6158
QCString removeAnonymousScopes(const QCString &s)
Definition: util.cpp:166
int findIndex(const StringVector &sv, const std::string &s)
find the index of a string in a vector of strings, returns -1 if the string could not be found ...
Definition: util.cpp:7319
int lineBlock(const QCString &text, const QCString &marker)
Returns the line number of the line following the line with the marker.
Definition: util.cpp:6498
int getPrefixIndex(const QCString &name)
Definition: util.cpp:3357
int extractClassNameFromType(const QCString &type, int &pos, QCString &name, QCString &templSpec, SrcLangExt=SrcLangExt_Unknown)
Definition: util.cpp:4338
QCString getOverloadDocs()
Definition: util.cpp:4212
A list of MemberDef objects as shown in documentation sections.
Definition: memberlist.h:81
class that provide information about a section.
Definition: section.h:49
Class representing a regular expression.
Definition: regex.h:35
Ordered dictionary of FileName objects.
Definition: filename.h:72
QCString getFileFilter(const QCString &name, bool isSourceCode)
Definition: util.cpp:1315
QCString extractDirection(QCString &docs)
Strip the direction part from docs and return it as a string in canonical form The input docs string ...
Definition: util.cpp:6801
Buffer used to store strings.
Definition: bufstr.h:29
bool findAndRemoveWord(QCString &s, const char *word)
removes occurrences of whole word from sentence, while keeps internal spaces and reducing multiple se...
Definition: util.cpp:5351
int guessSection(const QCString &name)
Definition: util.cpp:331
QCString correctURL(const QCString &url, const QCString &relPath)
Corrects URL url according to the relative path relPath.
Definition: util.cpp:6573
Class representing a directory in the file system.
Definition: dir.h:68
A model of a page symbol.
Definition: pagedef.h:25
QCString correctId(const QCString &s)
Definition: util.cpp:3941
Class representing a list of output generators that are written to in parallel.
Definition: outputlist.h:37
bool containsWord(const QCString &s, const char *word)
returns TRUE iff string s contains word w
Definition: util.cpp:5335
bool checkIfTypedef(const Definition *scope, const FileDef *fileScope, const QCString &n)
Definition: util.cpp:5684
Protection
Protection level of members.
Definition: types.h:26
QCString convertToHtml(const QCString &s, bool keepEntities=TRUE)
Definition: util.cpp:4063
std::string join(const StringVector &s, const std::string &delimiter)
create a string where the string in the vector are joined by the given delimiter
Definition: util.cpp:7334
QCString substituteTemplateArgumentsInString(const QCString &name, const ArgumentList &formalArgs, const std::unique_ptr< ArgumentList > &actualArgs)
Definition: util.cpp:4477
void convertProtectionLevel(MemberListType inListType, Protection inProt, int *outListType1, int *outListType2)
Computes for a given list type inListType, which are the the corresponding list type(s) in the base c...
Definition: util.cpp:6851
Data associated with a HSV colored image.
Definition: util.h:376
This is an alternative implementation of QCString.
Definition: qcstring.h:108
A model of a group of symbols.
Definition: groupdef.h:49
QCString convertToXML(const QCString &s, bool keepEntities=FALSE)
Definition: util.cpp:3948
QCString convertToId(const QCString &s)
Definition: util.cpp:3908
Implements TextGeneratorIntf for an OutputDocInterface stream.
Definition: util.h:72
A abstract class representing of a compound symbol.
Definition: classdef.h:103
int getScopeFragment(const QCString &s, int p, int *l)
Definition: util.cpp:4702
SrcLangExt getLanguageFromCodeLang(QCString &fileName)
Routine to handle the language attribute of the `.
Definition: util.cpp:5592
QCString getLanguageSpecificSeparator(SrcLangExt lang, bool classScope=FALSE)
Returns the scope separator to use given the programming language lang.
Definition: util.cpp:6545
bool isURL(const QCString &url)
Checks whether the given url starts with a supported protocol.
Definition: util.cpp:6561
bool resolveRef(const QCString &scName, const QCString &name, bool inSeeBlock, const Definition **resContext, const MemberDef **resMember, bool lookForSpecializations=TRUE, const FileDef *currentFile=0, bool checkScope=FALSE)
Definition: util.cpp:2757
Minimal replacement for QFileInfo.
Definition: fileinfo.h:22