definition.cpp File Reference

#include "definition.h"
#include <algorithm>
#include <mutex>
#include <optional>
#include <string>
#include <unordered_map>
#include "anchor.h"
#include "config.h"
#include "debug.h"
#include "definitionimpl.h"
#include "dirdef.h"
#include "doxygen.h"
#include "filedef.h"
#include "fileinfo.h"
#include "groupdef.h"
#include "htags.h"
#include "language.h"
#include "md5hash.h"
#include "message.h"
#include "namespacedef.h"
#include "outputlist.h"
#include "pagedef.h"
#include "parserintf.h"
#include "portable.h"
#include "reflist.h"
#include "regex.h"
#include "section.h"
#include "utf8.h"
#include "util.h"

Include dependency graph for definition.cpp:

Go to the source code of this file.

Classes
struct	ResettableOnce
	once_flag wrapper that is copyable (copy default-initializes the flag) and resettable. More...
class	DefinitionImpl::Private
	Private data associated with a Symbol DefinitionImpl object. More...
class	FilterCache
struct	FilterCache::FilterCacheItem

Functions
static bool	matchExcludedSymbols (const DString &name)
static void	addToMap (const DString &name, Definition *d)
static void	removeFromMap (const DString &name, Definition *d)
bool	readCodeFragment (const DString &fileName, bool isMacro, int &startLine, int &endLine, DString &result)
	Reads a fragment from file fileName starting with line startLine and ending with line endLine.
static MemberVector	refMapToVector (const std::unordered_map< std::string, MemberDef * > &map)
static bool	stripWord (DString &s, DString w)
static DString	abbreviate (const DString &s, const DString &name)
Definition *	toDefinition (DefinitionMutable *dm)
DefinitionMutable *	toDefinitionMutable (Definition *d)

Variables
static std::mutex	g_memberReferenceMutex

Function Documentation

abbreviate()

DString abbreviate ( const DString & s, const DString & name )

static

Definition at line 1606 of file definition.cpp.

{
  DString scopelessName=name;
  if (size_t i=scopelessName.rfind("::"); i!=DString::npos) scopelessName=scopelessName.mid(i+2);
  DString result=s;
  result=result.stripWhiteSpace();
  // strip trailing .
  if (!result.empty() && result.at(result.length()-1)=='.')
    result=result.left(result.length()-1);
 
  // strip any predefined prefix
  StringVector briefDescAbbrev = Config_getList(ABBREVIATE_BRIEF);
  for (const auto &p : briefDescAbbrev)
  {
    DString str = substitute(p,"$name",scopelessName); // replace $name with entity name
    str += " ";
    stripWord(result,str);
  }
 
  // capitalize first character
  if (!result.empty())
  {
    char c = result[0];
    if (c >= 'a' && c <= 'z') result[0] += 'A' - 'a';
  }
 
  return result;
}

References DString::at(), Config_getList, DString::empty(), DString::left(), DString::length(), DString::mid(), DString::npos, DString::rfind(), DString::stripWhiteSpace(), stripWord(), and substitute().

Referenced by DefinitionImpl::briefDescription().

addToMap()

void addToMap ( const DString & name, Definition * d )

static

Definition at line 226 of file definition.cpp.

{
  bool vhdlOpt = Config_getBool(OPTIMIZE_OUTPUT_VHDL);
  DString symbolName = name;
  int index=computeQualifiedIndex(symbolName);
  if (!vhdlOpt && index!=-1) symbolName=symbolName.mid(index+2);
  if (!symbolName.empty())
  {
    //printf("adding symbol %s\n",qPrint(symbolName));
    Doxygen::symbolMap->add(symbolName,d);
 
    d->_setSymbolName(symbolName);
  }
}

References Definition::_setSymbolName(), SymbolMap< T >::add(), computeQualifiedIndex(), Config_getBool, DString::empty(), DString::mid(), DefinitionImpl::name(), Doxygen::symbolMap, and DefinitionImpl::symbolName().

Referenced by DefinitionImpl::DefinitionImpl(), DefinitionImpl::DefinitionImpl(), and DefinitionAliasImpl::init().

matchExcludedSymbols()

bool matchExcludedSymbols ( const DString & name )

static

Definition at line 165 of file definition.cpp.

{
  StringVector exclSyms = Config_getList(EXCLUDE_SYMBOLS);
  if (exclSyms.empty()) return false; // nothing specified
  const std::string &symName = name.str();
  for (const auto &pat : exclSyms)
  {
    DString pattern = pat;
    bool forceStart=false;
    bool forceEnd=false;
    if (pattern.at(0)=='^')
    {
      pattern    = pattern.mid(1);
      forceStart = true;
    }
    if (pattern.at(pattern.length() - 1) == '$')
    {
      pattern  = pattern.left(pattern.length() - 1);
      forceEnd = true;
    }
    if (pattern.find('*')!=DString::npos) // wildcard mode
    {
      const reg::Ex re(substitute(pattern,"*",".*").str());
      reg::Match match;
      if (reg::search(symName,match,re)) // wildcard match
      {
        size_t ui = match.position();
        size_t pl = match.length();
        size_t sl = symName.length();
        if ((ui==0     || pattern.at(0)=='*'                  || (!isId(symName.at(ui-1))  && !forceStart)) &&
            (ui+pl==sl || pattern.at(pattern.length()-1)=='*' || (!isId(symName.at(ui+pl)) && !forceEnd))
           )
        {
          //printf("--> name=%s pattern=%s match at %d\n",qPrint(symName),qPrint(pattern),i);
          return true;
        }
      }
    }
    else if (!pattern.empty()) // match words
    {
      size_t i = symName.find(pattern.str());
      if (i!=std::string::npos) // we have a match!
      {
        size_t ui=i;
        size_t pl=pattern.length();
        size_t sl=symName.length();
        // check if it is a whole word match
        if ((ui==0     || (!isId(symName.at(ui-1))  && !forceStart)) &&
            (ui+pl==sl || (!isId(symName.at(ui+pl)) && !forceEnd))
           )
        {
          //printf("--> name=%s pattern=%s match at %d\n",qPrint(symName),qPrint(pattern),i);
          return true;
        }
      }
    }
  }
  //printf("--> name=%s: no match\n",name);
  return false;
}

References DString::at(), Config_getList, DString::empty(), DString::find(), isId(), DString::left(), DString::length(), DString::mid(), DefinitionImpl::name(), DString::npos, reg::search(), DString::str(), and substitute().

Referenced by DefinitionImpl::DefinitionImpl().

readCodeFragment()

bool readCodeFragment	(	const DString &	fileName,
		bool	isMacro,
		int &	startLine,
		int &	endLine,
		DString &	result )

Reads a fragment from file fileName starting with line startLine and ending with line endLine.

Reads a fragment of code from file fileName starting at line startLine and ending at line endLine (inclusive). The fragment is stored in result. If false is returned the code fragment could not be found.

The file is scanned for a opening bracket ('{') from startLine onward The line actually containing the bracket is returned via startLine. The file is scanned for a closing bracket ('}') from endLine backward. The line actually containing the bracket is returned via endLine. Note that for VHDL code the bracket search is not done.

The result is returned as a string via result. The function returns true if successful and false in case of an error.

Definition at line 760 of file definition.cpp.

{
  bool filterSourceFiles = Config_getBool(FILTER_SOURCE_FILES);
  DString filter = getFileFilter(fileName,true);
  bool usePipe = !filter.empty() && filterSourceFiles;
  int tabSize = Config_getInt(TAB_SIZE);
  SrcLangExt lang = getLanguageFromFileName(fileName);
  const int blockSize = 4096;
  std::string str;
  FilterCache::instance().getFileContents(fileName,
                                          static_cast<size_t>(std::max(1,startLine)),
                                          static_cast<size_t>(std::max({1,startLine,endLine})),str);
  //printf("readCodeFragment(%s,startLine=%d,endLine=%d)=\n[[[\n%s]]]\n",qPrint(fileName),startLine,endLine,qPrint(str));
 
  bool found = lang==SrcLangExt::VHDL   ||
               lang==SrcLangExt::Python ||
               lang==SrcLangExt::Fortran ||
               isMacro;
               // for VHDL, Python, and Fortran no bracket search is possible
  char *p=str.data();
  if (p && *p)
  {
    char c=0;
    int col=0;
    int lineNr=startLine;
    // skip until the opening bracket or lonely : is found
    char cn=0;
    while (*p && !found)
    {
      int pc=0;
      while ((c=*p++)!='{' && c!=':' && c!='=' && c!=0)
      {
        //printf("parsing char '%c'\n",c);
        if (c=='\n')
        {
          lineNr++;
          col = 0;
        }
        else if (c=='\t')
        {
          col+=tabSize - (col%tabSize);
        }
        else if (pc=='/' && c=='/') // skip single line comment
        {
          while ((c=*p++)!='\n' && c!=0);
          if (c == '\n')
          {
            lineNr++;
            col = 0;
          }
        }
        else if (pc=='/' && c=='*') // skip C style comment
        {
          while (((c=*p++)!='/' || pc!='*') && c!=0)
          {
            if (c == '\n')
            {
              lineNr++;
              col = 0;
            }
            pc=c;
          }
        }
        else
        {
          col++;
        }
        pc = c;
      }
      if (c==':')
      {
        cn=*p++;
        if (cn!=':') found=true;
      }
      else if (c=='=')
      {
        cn=*p++;
        if (cn=='>') // C# Expression body
        {
          found=true;
        }
      }
      else if (c=='{')
      {
        found=true;
      }
      else if (c==0)
      {
        break;
      }
    }
    //printf(" -> readCodeFragment(%s,%d,%d) lineNr=%d\n",fileName,startLine,endLine,lineNr);
    if (found)
    {
      // For code with more than one line,
      // fill the line with spaces until we are at the right column
      // so that the opening brace lines up with the closing brace
      if (endLine!=startLine)
      {
        DString spaces;
        spaces.fill(' ',col);
        result+=spaces;
      }
      // copy until end of line
      if (c) result+=c;
      startLine=lineNr;
      if (c==':' || c=='=')
      {
        result+=cn;
        if (cn=='\n') lineNr++;
      }
      char lineStr[blockSize];
      do
      {
        //printf("reading line %d in range %d-%d\n",lineNr,startLine,endLine);
        int size_read=0;
        do
        {
          // read up to blockSize-1 non-zero characters
          int i=0;
          while ((c=*p) && i<blockSize-1)
          {
            lineStr[i++]=c;
            p++;
            if (c=='\n') break; // stop at end of the line
          }
          lineStr[i]=0;
          size_read=i;
          result+=lineStr; // append line to the output
        } while (size_read == (blockSize-1)); // append more if line does not fit in buffer
        lineNr++;
      } while (*p);
 
      // strip stuff after closing bracket
      size_t newLineIndex = result.rfind('\n');
      size_t braceIndex   = result.rfind('}');
      if (newLineIndex!=DString::npos && braceIndex!=DString::npos && braceIndex > newLineIndex)
      {
        result.resize(braceIndex+1);
      }
      endLine=lineNr-1;
    }
    if (usePipe)
    {
      Debug::print(Debug::FilterOutput, 0, "Filter output\n");
      Debug::print(Debug::FilterOutput,0,"-------------\n{}\n-------------\n",result);
    }
  }
  DString encoding = getEncoding(FileInfo(fileName.str()));
  if (encoding!="UTF-8")
  {
    std::string encBuf = result.str();
    bool ok = transcodeCharacterStringToUTF8(encBuf,encoding.data());
    if (ok)
    {
      result = encBuf;
    }
    else
    {
      err("failed to transcode characters in code fragment in file {} lines {} to {}, from input encoding {} to UTF-8\n",
          fileName,startLine,endLine,encoding);
 
    }
  }
  if (!result.empty() && result.at(result.length()-1)!='\n') result += "\n";
  //printf("readCodeFragment(%d-%d)=%s\n",startLine,endLine,qPrint(result));
  return found;
}

References DString::at(), Config_getBool, Config_getInt, DString::data(), DString::empty(), err, DString::fill(), Debug::FilterOutput, getEncoding(), FilterCache::getFileContents(), getFileFilter(), getLanguageFromFileName(), FilterCache::instance(), DString::length(), DString::npos, Debug::print(), DString::resize(), DString::rfind(), DString::str(), and transcodeCharacterStringToUTF8().

Referenced by VhdlDocGen::createFlowChart(), DefinitionMutable::toDefinition_(), and DefinitionImpl::writeInlineCode().

refMapToVector()

MemberVector refMapToVector ( const std::unordered_map< std::string, MemberDef * > & map )

inlinestatic

Definition at line 1088 of file definition.cpp.

{
  // convert map to a vector of values
  MemberVector result;
  std::transform(map.begin(),map.end(),      // iterate over map
                 std::back_inserter(result), // add results to vector
                 [](const auto &item)
                 { return item.second; }     // extract value to add from map Key,Value pair
                );
  // and sort it
  std::stable_sort(result.begin(),result.end(),
              [](const auto &m1,const auto &m2) { return genericCompareMembers(m1,m2)<0; });
  return result;
}

References MemberVector::begin(), and MemberVector::end().

Referenced by DefinitionImpl::_writeSourceRefList(), DefinitionImpl::getReferencedByMembers(), and DefinitionImpl::getReferencesMembers().

removeFromMap()

void removeFromMap ( const DString & name, Definition * d )

static

Definition at line 241 of file definition.cpp.

{
  Doxygen::symbolMap->remove(name,d);
}

References DefinitionImpl::name(), SymbolMap< T >::remove(), and Doxygen::symbolMap.

Referenced by DefinitionAliasImpl::deinit(), and DefinitionImpl::~DefinitionImpl().

stripWord()

bool stripWord ( DString & s, DString w )

static

Definition at line 1593 of file definition.cpp.

{
  bool success=false;
  if (s.left(w.length())==w)
  {
    success=true;
    s=s.mid(w.length());
  }
  return success;
}

References DString::left(), DString::length(), and DString::mid().

Referenced by abbreviate().

toDefinition()

Definition * toDefinition

(

DefinitionMutable *

dm

)

Definition at line 1981 of file definition.cpp.

{
  return dm ? dm->toDefinition_() : nullptr;
}

References DefinitionImpl::_docsAlreadyAdded(), DefinitionImpl::docFile(), DefinitionImpl::docLine(), DString::empty(), DefinitionImpl::p, stripLeadingAndTrailingEmptyLines(), and stripWhiteSpace().

Referenced by buildScopeFromQualifiedName(), endFileWithNavPath(), findScopeFromQualifiedName(), toClassDef(), toConceptDef(), toMemberDef(), toNamespaceDef(), and MemberList::writeDocumentationPage().

toDefinitionMutable()

DefinitionMutable * toDefinitionMutable

(

Definition *

d

)

Definition at line 1986 of file definition.cpp.

{
  return d ? d->toDefinitionMutable_() : nullptr;
}

References Doxygen::clangUsrMap, and DefinitionImpl::p.

Referenced by addConceptToContext(), buildNamespaceList(), buildScopeFromQualifiedName(), computeTooltipTexts(), createTagLessInstance(), resolveClassNestingRelations(), and DefinitionMutable::toDefinition_().

Variable Documentation

g_memberReferenceMutex

std::mutex g_memberReferenceMutex

static

Definition at line 1776 of file definition.cpp.

Referenced by DefinitionImpl::getReferencedByMembers(), and DefinitionImpl::getReferencesMembers().