A bunch of utility functions. More...

#include <memory>
#include <unordered_map>
#include <algorithm>
#include <functional>
#include <fstream>
#include <variant>
#include <string_view>
#include <ctype.h>
#include "types.h"
#include "docparser.h"
#include "containers.h"
#include "outputgen.h"
#include "regex.h"
#include "conceptdef.h"
#include "construct.h"

Include dependency graph for util.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	TextGeneratorIntf
	Abstract interface for a hyperlinked text fragment. More...

class	TextGeneratorOLImpl
	Implements TextGeneratorIntf for an OutputDocInterface stream. More...

struct	GetDefInput

struct	GetDefResult

struct	SelectionBlock

struct	SelectionMarkerInfo

struct	KeywordSubstitution

struct	ColoredImgDataItem
	Data associated with a HSV colored image. More...

Typedefs
using	SelectionBlockList = std::vector< SelectionBlock >

using	KeywordSubstitutionList = std::vector< KeywordSubstitution >

Functions
QCString	langToString (SrcLangExt lang)
	Returns a string representation of lang. More...

QCString	getLanguageSpecificSeparator (SrcLangExt lang, bool classScope=FALSE)
	Returns the scope separator to use given the programming language lang.

void	linkifyText (const TextGeneratorIntf &ol, const Definition scope, const FileDef fileScope, const Definition *self, const QCString &text, bool autoBreak=FALSE, bool external=TRUE, bool keepSpaces=FALSE, int indentLevel=0)

QCString	fileToString (const QCString &name, bool filter=FALSE, bool isSourceCode=FALSE)

GetDefResult	getDefs (const GetDefInput &input)

QCString	getFileFilter (const QCString &name, bool isSourceCode)

bool	resolveRef (const QCString &scName, const QCString &name, bool inSeeBlock, const Definition resContext, const MemberDef resMember, bool lookForSpecializations=TRUE, const FileDef *currentFile=nullptr, bool checkScope=FALSE)

bool	resolveLink (const QCString &scName, const QCString &lr, bool inSeeBlock, const Definition **resContext, QCString &resAnchor, const QCString &prefix=QCString())

bool	generateLink (OutputList &ol, const QCString &, const QCString &, bool inSeeBlock, const QCString &)

void	generateFileRef (OutputList &ol, const QCString &, const QCString &linkTxt=QCString())

void	writePageRef (OutputList &ol, const QCString &cn, const QCString &mn)

bool	matchArguments2 (const Definition srcScope, const FileDef srcFileScope, const ArgumentList srcAl, const Definition dstScope, const FileDef dstFileScope, const ArgumentList dstAl, bool checkCV, SrcLangExt lang)

void	mergeArguments (ArgumentList &, ArgumentList &, bool forceNameOverwrite=FALSE)

QCString	substituteClassNames (const QCString &s)

QCString	selectBlocks (const QCString &s, const SelectionBlockList &blockList, const SelectionMarkerInfo &markerInfo)
	remove disabled blocks and all block markers from s and return the result as a string

void	checkBlocks (const QCString &s, const QCString fileName, const SelectionMarkerInfo &markerInfo)

QCString	removeEmptyLines (const QCString &s)

FileDef *	findFileDef (const FileNameLinkedMap *fnMap, const QCString &n, bool &ambig)

QCString	findFilePath (const QCString &file, bool &ambig)

QCString	showFileDefMatches (const FileNameLinkedMap *fnMap, const QCString &n)

EntryType	guessSection (const QCString &name)

bool	isId (int c)

bool	isIdJS (int c)

QCString	removeRedundantWhiteSpace (const QCString &s)

QCString	inlineArgListToDoc (const ArgumentList &al)

QCString	argListToString (const ArgumentList &al, bool useCanonicalType=FALSE, bool showDefVals=TRUE)

QCString	tempArgListToString (const ArgumentList &al, SrcLangExt lang, bool includeDefaults=true)

QCString	generateMarker (int id)

void	writeExamples (OutputList &ol, const ExampleList &el)

QCString	stripAnonymousNamespaceScope (const QCString &s)

QCString	stripFromPath (const QCString &path)

QCString	stripFromIncludePath (const QCString &path)

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

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

QCString	substituteKeywords (const QCString &s, const KeywordSubstitutionList &keywords)

QCString	substituteKeywords (const QCString &s, const QCString &title, const QCString &projName, const QCString &projNum, const QCString &projBrief)

int	getPrefixIndex (const QCString &name)

QCString	removeAnonymousScopes (const QCString &s)

QCString	replaceAnonymousScopes (const QCString &s, const QCString &replacement=QCString())

QCString	convertNameToFile (const QCString &name, bool allowDots=FALSE, bool allowUnderscore=FALSE)

void	extractNamespaceName (const QCString &scopeName, QCString &className, QCString &namespaceName, bool allowEmptyClass=FALSE)

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

QCString	stripScope (const QCString &name)

QCString	convertToId (const QCString &s)

QCString	correctId (const QCString &s)

QCString	convertToHtml (const QCString &s, bool keepEntities=TRUE)

QCString	convertToXML (const QCString &s, bool keepEntities=FALSE)

QCString	convertToJSString (const QCString &s)

QCString	getOverloadDocs ()

void	addMembersToMemberGroup (MemberList ml, MemberGroupList pMemberGroups, const Definition *context)

int	extractClassNameFromType (const QCString &type, int &pos, QCString &name, QCString &templSpec, SrcLangExt=SrcLangExt::Unknown)

QCString	normalizeNonTemplateArgumentsInString (const QCString &name, const Definition *context, const ArgumentList &formalArgs)

QCString	substituteTemplateArgumentsInString (const QCString &name, const ArgumentList &formalArgs, const ArgumentList *actualArgs)

QCString	stripTemplateSpecifiersFromScope (const QCString &fullName, bool parentOnly=TRUE, QCString *lastScopeStripped=nullptr, QCString scopeName=QCString(), bool allowArtificial=true)

QCString	resolveTypeDef (const Definition d, const QCString &name, const Definition *typedefContext=nullptr)

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

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

void	addRefItem (const RefItemVector &sli, const QCString &key, const QCString &prefix, const QCString &name, const QCString &title, const QCString &args, const Definition *scope)

PageDef *	addRelatedPage (const QCString &name, const QCString &ptitle, const QCString &doc, const QCString &fileName, int docLine, int startLine, const RefItemVector &sli=RefItemVector(), GroupDef gd=nullptr, const TagInfo tagInfo=nullptr, bool xref=FALSE, SrcLangExt lang=SrcLangExt::Unknown)

bool	getCaseSenseNames ()

QCString	escapeCharsInString (const QCString &name, bool allowDots, bool allowUnderscore=FALSE)

QCString	unescapeCharsInString (const QCString &s)

void	addGroupListToTitle (OutputList &ol, const Definition *d)

QCString	linkToText (SrcLangExt lang, const QCString &link, bool isFileName)

bool	checkExtension (const QCString &fName, const QCString &ext)

void	addHtmlExtensionIfMissing (QCString &fName)

QCString	stripExtensionGeneral (const QCString &fName, const QCString &ext)

QCString	stripExtension (const QCString &fName)

void	replaceNamespaceAliases (QCString &scope, size_t i)

int	computeQualifiedIndex (const QCString &name)
	Return the index of the last :: in the string name that is still before the first <.

void	addDirPrefix (QCString &fileName)

QCString	relativePathToRoot (const QCString &name)

QCString	determineAbsoluteIncludeName (const QCString &curFile, const QCString &incFileName)

void	createSubDirs (const Dir &d)

void	clearSubDirs (const Dir &d)

QCString	removeLongPathMarker (QCString path)

QCString	stripPath (const QCString &s)

bool	containsWord (const QCString &s, const char *word)
	returns `TRUE` iff string s contains word w

bool	findAndRemoveWord (QCString &s, const char *word)
	removes occurrences of whole word from sentence, while keeps internal spaces and reducing multiple sequences of spaces. More...

QCString	stripLeadingAndTrailingEmptyLines (const QCString &s, int &docLine)
	Special version of QCString::stripWhiteSpace() that only strips completely blank lines. More...

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

SrcLangExt	getLanguageFromFileName (const QCString &fileName, SrcLangExt defLang=SrcLangExt::Cpp)

SrcLangExt	getLanguageFromCodeLang (QCString &fileName)
	Routine to handle the language attribute of the `. More...

QCString	getFileNameExtension (const QCString &fn)

void	initDefaultExtensionMapping ()

void	addCodeOnlyMappings ()

bool	checkIfTypedef (const Definition scope, const FileDef fileScope, const QCString &n)

QCString	parseCommentAsText (const Definition scope, const MemberDef member, const QCString &doc, const QCString &fileName, int lineNr)

bool	transcodeCharacterStringToUTF8 (std::string &input, const char *inputEncoding)

QCString	recodeString (const QCString &str, const char fromEncoding, const char toEncoding)

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

QCString	convertCharEntitiesToUTF8 (const QCString &s)

void	stackTrace ()

bool	readInputFile (const QCString &fileName, std::string &contents, bool filter=TRUE, bool isSourceCode=FALSE)
	read a file name fileName and optionally filter and transcode it

QCString	filterTitle (const QCString &title)

bool	patternMatch (const FileInfo &fi, const StringVector &patList)

QCString	externalLinkTarget (const bool parent=false)

QCString	createHtmlUrl (const QCString &relPath, const QCString &ref, bool href, bool islocalFile, const QCString &targetFileName, const QCString &anchor)

QCString	externalRef (const QCString &relPath, const QCString &ref, bool href)

int	nextUtf8CharPosition (const QCString &utf8Str, uint32_t len, uint32_t startPos)

void	writeMarkerList (OutputList &ol, const std::string &markerText, size_t numMarkers, std::function< void(size_t)> replaceFunc)

void	writeColoredImgData (const QCString &dir, ColoredImgDataItem data[])
	Writes the intensity only bitmap represented by data as an image to directory dir using the colors defined by HTML_COLORSTYLE_*.

QCString	replaceColorMarkers (const QCString &str)
	Replaces any markers of the form ##AA in input string str by new markers of the form #AABBCC, where #AABBCC represents a valid color, based on the intensity represented by hex number AA and the current HTML_COLORSTYLE_* settings.

bool	copyFile (const QCString &src, const QCString &dest)
	Copies the contents of file with name src to the newly created file with name dest. More...

int	lineBlock (const QCString &text, const QCString &marker)
	Returns the line number of the line following the line with the marker. More...

bool	isURL (const QCString &url)
	Checks whether the given url starts with a supported protocol.

QCString	correctURL (const QCString &url, const QCString &relPath)
	Corrects URL url according to the relative path relPath. More...

QCString	processMarkup (const QCString &s)

bool	protectionLevelVisible (Protection prot)

QCString	stripIndentation (const QCString &s)

void	stripIndentation (QCString &doc, const int indentationLevel)

QCString	getDotImageExtension ()

bool	fileVisibleInIndex (const FileDef *fd, bool &genSourceFile)

QCString	extractDirection (QCString &docs)
	Strip the direction part from docs and return it as a string in canonical form The input docs string can start with e.g. More...

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 class that are to be added to this list. More...

bool	mainPageHasTitle ()

bool	openOutputFile (const QCString &outFile, std::ofstream &f)

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 between the delimiters

StringVector	split (const std::string &s, const reg::Ex &delimiter)
	split input string s by regular expression delimiter delimiter. returns a vector of non-empty strings that are between the delimiters

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

int	findIndex (const std::string &s, const reg::Ex &re)
	find the index of the first occurrence of pattern re in a string s returns -1 if the pattern could not be found

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

bool	recognizeFixedForm (const QCString &contents, FortranFormat format)

FortranFormat	convertFileNameFortranParserCode (QCString fn)

QCString	integerToAlpha (int n, bool upper=true)

QCString	integerToRoman (int n, bool upper=true)

QCString	getEncoding (const FileInfo &fi)

QCString	fixSpaces (const QCString &s)

QCString	detab (const QCString &s, size_t &refIndent)

QCString	getProjectId ()

QCString	projectLogoFile ()

void	mergeMemberOverrideOptions (MemberDefMutable md1, MemberDefMutable md2)

Detailed Description

A bunch of utility functions.

Function Documentation

◆ checkIfTypedef()

bool checkIfTypedef	(	const Definition *	scope,
		const FileDef *	fileScope,
		const QCString &	n
	)

Returns true iff the given name string appears to be a typedef in scope.

◆ convertNameToFile()

QCString convertNameToFile	(	const QCString &	name,
		bool	allowDots,
		bool	allowUnderscore
	)

This function determines the file name on disk of an item given its name, which could be a class name with template arguments, so special characters need to be escaped.

◆ convertProtectionLevel()

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 class that are to be added to this list.

So for public inheritance, the mapping is 1-1, so outListType1=inListType Private members are to be hidden completely.

For protected inheritance, both protected and public members of the base class should be joined in the protected member section.

For private inheritance, both protected and public members of the base class should be joined in the private member section.

◆ convertToHtml()

QCString convertToHtml	(	const QCString &	s,
		bool	keepEntities
	)

Converts a string to a HTML-encoded string

◆ convertToId()

QCString convertToId ( const QCString & s )

Converts a string to a HTML id string

◆ convertToXML()

QCString convertToXML	(	const QCString &	s,
		bool	keepEntities
	)

Converts a string to an XML-encoded string

◆ copyFile()

bool copyFile	(	const QCString &	src,
		const QCString &	dest
	)

Copies the contents of file with name src to the newly created file with name dest.

Returns TRUE if successful.

◆ correctId()

QCString correctId ( const QCString & s )

Some strings have been corrected but the requirement regarding the fact that an id cannot have a digit at the first position. To overcome problems with double labels we always place an "a" in front

◆ correctURL()

QCString correctURL	(	const QCString &	url,
		const QCString &	relPath
	)

Corrects URL url according to the relative path relPath.

Returns the corrected URL. For absolute URLs no correction will be done.

◆ extractClassNameFromType()

int extractClassNameFromType	(	const QCString &	type,
		int &	pos,
		QCString &	name,
		QCString &	templSpec,
		SrcLangExt	lang
	)

Extracts a (sub-)string from type starting at pos that could form a class. The index of the match is returned and the found class name and a template argument list templSpec. If -1 is returned there are no more matches.

◆ extractDirection()

QCString extractDirection ( QCString & docs )

Strip the direction part from docs and return it as a string in canonical form The input docs string can start with e.g.

"[in]", "[in, out]", "[inout]", "[out,in]"...

Returns: either "[in,out]", "[in]", or "[out]" or the empty string.

◆ extractNamespaceName()

void extractNamespaceName	(	const QCString &	scopeName,
		QCString &	className,
		QCString &	namespaceName,
		bool	allowEmptyClass
	)

Input is a scopeName, output is the scopename split into a namespace part (as large as possible) and a classname part.

◆ fileToString()

QCString fileToString	(	const QCString &	name,
		bool	filter,
		bool	isSourceCode
	)

reads a file with name name and returns it as a string. If filter is TRUE the file will be filtered by any user specified input filter. If name is "-" the string will be read from standard input.

◆ findAndRemoveWord()

bool findAndRemoveWord	(	QCString &	sentence,
		const char *	word
	)

removes occurrences of whole word from sentence, while keeps internal spaces and reducing multiple sequences of spaces.

Example: sentence=cat+ catfish cat cat concat cat, word=cat returns: + catfish concat

◆ generateMarker()

QCString generateMarker ( int id )

Generate a place holder for a position in a list. Used for translators to be able to specify different elements orders depending on whether text flows from left to right or visa versa.

◆ getFileFilter()

QCString getFileFilter	(	const QCString &	name,
		bool	isSourceCode
	)

looks for a filter for the file name. Returns the name of the filter if there is a match for the file name, otherwise an empty string. In case inSourceCode is TRUE then first the source filter list is considered.

◆ getLanguageFromCodeLang()

SrcLangExt getLanguageFromCodeLang ( QCString & fileName )

Routine to handle the language attribute of the `.

` command

◆ getOverloadDocs()

QCString getOverloadDocs ( )

Returns the standard string that is generated when the \overload command is used.

◆ getPrefixIndex()

int getPrefixIndex ( const QCString & name )

Returns the character index within name of the first prefix in Config_getList(IGNORE_PREFIX) that matches name at the left hand side, or zero if no match was found

◆ getScopeFragment()

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

Returns a fragment from scope s, starting at position p.

Parameters

s	the scope name as a string.
p	the start position (0 is the first).
l	the resulting length of the fragment.

Returns: the location of the fragment, or -1 if non is found.

◆ guessSection()

EntryType guessSection ( const QCString & name )

try to determine if name is a source or a header file name by looking at the extension. A number of variations is allowed in both upper and lower case) If anyone knows or uses another extension please let me know :-)

◆ langToString()

QCString langToString ( SrcLangExt lang )

Returns a string representation of lang.

◆ lineBlock()

int lineBlock	(	const QCString &	text,
		const QCString &	marker
	)

Returns the line number of the line following the line with the marker.

See also: routine extractBlock

◆ mergeScopes()

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

Merges two scope parts together. The parts may (partially) overlap. Example1: A::B and B::C will result in A::B::C
Example2: A and B will be A::B
Example3: A::B and B will be A::B

Parameters

leftScope	the left hand part of the scope.
rightScope	the right hand part of the scope.

Returns: the merged scope.

◆ removeAnonymousScopes()

QCString removeAnonymousScopes ( const QCString & str )

Removes all anonymous scopes from string s Possible examples:

   "bla::@10::blep"      => "bla::blep"
   "bla::@10::@11::blep" => "bla::blep"
   "@10::blep"           => "blep"
   " @10::blep"          => "blep"
   "@9::@10::blep"       => "blep"
   "bla::@1"             => "bla"
   "bla::@1::@2"         => "bla"
   "bla @1"              => "bla"

◆ resolveRef()

bool resolveRef	(	const QCString &	scName,
		const QCString &	name,
		bool	inSeeBlock,
		const Definition **	resContext,
		const MemberDef **	resMember,
		bool	lookForSpecialization,
		const FileDef *	currentFile,
		bool	checkScope
	)

Returns an object to reference to given its name and context

Postcondition: return value TRUE implies *resContext!=0 or *resMember!=0

◆ stripFromIncludePath()

QCString stripFromIncludePath ( const QCString & path )

strip part of path if it matches one of the paths in the Config_getList(INCLUDE_PATH) list

◆ stripFromPath()

QCString stripFromPath ( const QCString & path )

strip part of path if it matches one of the paths in the Config_getList(STRIP_FROM_PATH) list

◆ stripLeadingAndTrailingEmptyLines()

QCString stripLeadingAndTrailingEmptyLines	(	const QCString &	s,
		int &	docLine
	)

Special version of QCString::stripWhiteSpace() that only strips completely blank lines.

Parameters

s	the string to be stripped
docLine	the line number corresponding to the start of the string. This will be adjusted based on the number of lines stripped from the start.

Returns: The stripped string.

◆ stripScope()

QCString stripScope ( const QCString & name )

Strips the scope from a name. Examples: A::B will return A and A<T>::B<N::C<D> > will return A<T>.

◆ stripTemplateSpecifiersFromScope()

QCString stripTemplateSpecifiersFromScope	(	const QCString &	fullName,
		bool	parentOnly,
		QCString *	pLastScopeStripped,
		QCString	scopeName,
		bool	allowArtificial
	)

Strips template specifiers from scope fullName, except those that make up specialized classes. The switch parentOnly determines whether or not a template "at the end" of a scope should be considered, e.g. with parentOnly is TRUE, A<T>::B<S> will try to strip <T> and not <S>, while parentOnly is FALSE will strip both unless A<T> or B<S> are specialized template classes.

◆ substituteTemplateArgumentsInString()

QCString substituteTemplateArgumentsInString	(	const QCString &	nm,
		const ArgumentList &	formalArgs,
		const ArgumentList *	actualArgs
	)

Substitutes any occurrence of a formal argument from argument list formalArgs in name by the corresponding actual argument in argument list actualArgs. The result after substitution is returned as a string. The argument name is used to prevent recursive substitution.

Classes

Typedefs

Functions

Detailed Description

Function Documentation

◆ checkIfTypedef()

◆ convertNameToFile()

◆ convertProtectionLevel()

◆ convertToHtml()

◆ convertToId()

◆ convertToXML()

◆ copyFile()

◆ correctId()

◆ correctURL()

◆ extractClassNameFromType()

◆ extractDirection()

◆ extractNamespaceName()

◆ fileToString()

◆ findAndRemoveWord()

◆ generateMarker()

◆ getFileFilter()

◆ getLanguageFromCodeLang()

◆ getOverloadDocs()

◆ getPrefixIndex()

◆ getScopeFragment()

◆ guessSection()

◆ langToString()

◆ lineBlock()

◆ mergeScopes()

◆ removeAnonymousScopes()

◆ resolveRef()

◆ stripFromIncludePath()

◆ stripFromPath()

◆ stripLeadingAndTrailingEmptyLines()

◆ stripScope()

◆ stripTemplateSpecifiersFromScope()

◆ substituteTemplateArgumentsInString()