CitationManager Class Reference

Citation manager class. More...

#include <src/cite.h>

Classes
struct	Private

Public Member Functions
void	insert (const QCString &label)
	Insert a citation identified by label into the database.
const CiteInfo *	find (const QCString &label) const
	Return the citation info for a given label.
void	generatePage ()
	Generate the citations page.
void	clear ()
	clears the database
bool	isEmpty () const
	return TRUE if there are no citations.
QCString	latexBibFiles ()
	lists the bibtex cite files in a comma separated list
QCString	fileName () const
QCString	anchorPrefix () const

Static Public Member Functions
static CitationManager &	instance ()

Private Member Functions
	CitationManager ()
	Create the database, with an expected maximum of size entries.
	~CitationManager ()=default
void	insertCrossReferencesForBibFile (const QCString &bibFile)
QCString	getFormulas (const QCString &s)
QCString	replaceFormulas (const QCString &s)

Private Attributes
std::unique_ptr< Private >	p

Detailed Description

Citation manager class.

This class provides access do the database of bibliographic references through the bibtex backend.

Definition at line 84 of file cite.h.

Constructor & Destructor Documentation

CitationManager()

CitationManager::CitationManager ( )

private

Create the database, with an expected maximum of size entries.

Definition at line 91 of file cite.cpp.

                                 : p(new Private)
{
}

References p.

Referenced by instance(), and ~CitationManager().

~CitationManager()

CitationManager::~CitationManager ( )

privatedefault

References CitationManager(), getFormulas(), insertCrossReferencesForBibFile(), and replaceFormulas().

Member Function Documentation

anchorPrefix()

QCString CitationManager::anchorPrefix

(

)

const

Definition at line 126 of file cite.cpp.

{
  return "CITEREF_";
}

Referenced by DocAnchor::DocAnchor(), DocCite::DocCite(), LatexDocVisitor::operator()(), and TextDocVisitor::operator()().

clear()

void CitationManager::clear

(

)

clears the database

Definition at line 110 of file cite.cpp.

{
  p->entries.clear();
}

References p.

Referenced by clearAll().

fileName()

QCString CitationManager::fileName

(

)

const

Definition at line 121 of file cite.cpp.

{
  return "citelist";
}

Referenced by DocAnchor::DocAnchor(), DocCite::DocCite(), and generatePage().

find()

const CiteInfo * CitationManager::find

(

const QCString &

label

)

const

Return the citation info for a given label.

Ownership of the info stays with the manager.

Definition at line 101 of file cite.cpp.

{
  if (auto it = p->entries.find(label.lower().str()); it != p->entries.end())
  {
    return it->second.get();
  }
  return nullptr;
}

References QCString::lower(), p, and QCString::str().

Referenced by DocAnchor::DocAnchor(), DocCite::DocCite(), DocCite::getText(), and insertCrossReferencesForBibFile().

generatePage()

void CitationManager::generatePage

(

)

Generate the citations page.

Definition at line 331 of file cite.cpp.

{
  //printf("** CitationManager::generatePage() count=%d\n",m_ordering.count());
 
  // do not generate an empty citations page
  if (isEmpty()) return; // nothing to cite
 
  bool citeDebug = Debug::isFlagSet(Debug::Cite);
 
  // 0. add cross references from the bib files to the cite dictionary
  const StringVector &citeDataList = Config_getList(CITE_BIB_FILES);
  for (const auto &bibdata : citeDataList)
  {
    QCString bibFile = getBibFile(bibdata);
    insertCrossReferencesForBibFile(bibFile);
  }
 
  // 1. generate file with markers and citations to OUTPUT_DIRECTORY
  QCString outputDir = Config_getString(OUTPUT_DIRECTORY);
  QCString citeListFile = outputDir+"/citelist.doc";
  {
    std::ofstream t = Portable::openOutputStream(citeListFile);
    if (!t.is_open())
    {
      err("could not open file {} for writing\n",citeListFile);
    }
    t << "<!-- BEGIN CITATIONS -->\n";
    t << "<!--\n";
    for (const auto &it : p->entries)
    {
      t << "\\citation{" << it.second->label() << "}\n";
    }
    t << "-->\n";
    t << "<!-- END CITATIONS -->\n";
    t << "<!-- BEGIN BIBLIOGRAPHY -->\n";
    t << "<!-- END BIBLIOGRAPHY -->\n";
    t.close();
  }
 
  // 2. generate bib2xhtml
  QCString bib2xhtmlFile  = outputDir+"/bib2xhtml.pl";
  ResourceMgr::instance().copyResource("bib2xhtml.pl",outputDir);
 
  // 3. generate doxygen.bst
  QCString doxygenBstFile = outputDir+"/doxygen.bst";
  ResourceMgr::instance().copyResource("doxygen.bst",outputDir);
 
  // 4. for all formats we just copy the bib files to as special output directory
  //    so bibtex can find them without path (bibtex doesn't support paths or
  //    filenames with spaces!)
  //    Strictly not required when only latex is generated
  QCString bibOutputDir = outputDir+"/"+bibTmpDir;
  QCString bibOutputFiles = "";
  Dir thisDir;
  if (!thisDir.exists(bibOutputDir.str()) && !thisDir.mkdir(bibOutputDir.str()))
  {
    err("Failed to create temporary output directory '{}', skipping citations\n",bibOutputDir);
    return;
  }
  int i = 0;
  for (const auto &bibdata : citeDataList)
  {
    QCString bibFile = getBibFile(bibdata);
    FileInfo fi(bibFile.str());
    if (fi.exists())
    {
      if (!bibFile.isEmpty())
      {
        ++i;
        std::ifstream f_org = Portable::openInputStream(bibFile);
        if (!f_org.is_open())
        {
          err("could not open file {} for reading\n",bibFile);
        }
        std::ofstream f_out = Portable::openOutputStream(bibOutputDir + bibTmpFile + QCString().setNum(i) + ".bib");
        if (!f_out.is_open())
        {
          err("could not open file {}{}{:d}{} for reading\n",bibOutputDir,bibTmpFile,i,".bib");
        }
        QCString docs;
        std::string lineStr;
        while (getline(f_org,lineStr))
        {
          docs += lineStr + "\n";
        }
        docs = getFormulas(docs);
        f_out << docs;
        if (f_org.is_open()) f_org.close();
        if (f_out.is_open()) f_out.close();
        bibOutputFiles = bibOutputFiles + " " + bibTmpDir + bibTmpFile + QCString().setNum(i) + ".bib";
      }
    }
  }
 
  std::string oldDir = Dir::currentDirPath();
  Dir::setCurrent(outputDir.str());
 
  // 5. run bib2xhtml perl script on the generated file which will insert the
  //    bibliography in citelist.doc
  QCString perlArgs = "\""+bib2xhtmlFile+"\" "+bibOutputFiles+" \""+ citeListFile+"\"";
  if (citeDebug) perlArgs+=" -d";
  int exitCode = Portable::system("perl",perlArgs);
  if (exitCode!=0)
  {
    err("Problems running bibtex. Verify that the command 'perl --version' works from the command line. Exit code: {}\n",
        exitCode);
  }
 
  Dir::setCurrent(oldDir);
 
  // 6. read back the file
  QCString doc;
  {
    std::ifstream f = Portable::openInputStream(citeListFile);
    if (!f.is_open())
    {
      err("could not open file {} for reading\n",citeListFile);
    }
 
    bool insideBib=FALSE;
    //printf("input=[%s]\n",qPrint(input));
    std::string lineStr;
    while (getline(f,lineStr))
    {
      QCString line(lineStr);
      //printf("pos=%d s=%d line=[%s]\n",pos,s,qPrint(line));
 
      if      (line.find("<!-- BEGIN BIBLIOGRAPHY")!=-1) insideBib=TRUE;
      else if (line.find("<!-- END BIBLIOGRAPH")!=-1)    insideBib=FALSE;
      // determine text to use at the location of the @cite command
      if (insideBib && ((i=line.find("name=\"CITEREF_"))!=-1 || (i=line.find("name=\"#CITEREF_"))!=-1))
      {
        int j=line.find("\">[");
        int j1=line.find("<!--[");
        int k=line.find("]<!--");
        int k1=line.find("]-->");
        if (j!=-1 && k!=-1)
        {
          size_t ui=static_cast<size_t>(i);
          size_t uj0=static_cast<size_t>(j);
          size_t uj=static_cast<size_t>(j1);
          size_t uk=static_cast<size_t>(k1);
          QCString label = line.mid(ui+14,uj0-ui-14);
          StringVector optList = split(line.mid(uj+5,uk-uj-5).str(),",");
          QCString number = optList[0];
          QCString shortAuthor = optList[1];
          QCString year;
          if (optList.size() == 3)
          {
            year = optList[2];
          }
          line = line.left(ui+14) + label + line.right(line.length()-uj0);
          auto it = p->entries.find(label.lower().str());
          //printf("label='%s' number='%s' => %p\n",qPrint(label),qPrint(number),it->second.get());
          if (it!=p->entries.end())
          {
            it->second->setText(number);
            it->second->setShortAuthor(shortAuthor);
            it->second->setYear(year.stripWhiteSpace());
          }
        }
      }
      if (insideBib) doc+=line+"\n";
    }
    //printf("doc=[%s]\n",qPrint(doc));
  }
 
  // 7. place formulas back and run the conversion of \f$ ... \f$ to the internal required format
  {
    doc = replaceFormulas(doc);
    Entry            current;
    bool             needsEntry = false;
    CommentScanner   commentScanner;
    int              lineNr = 0;
    int              pos = 0;
    GuardedSectionStack guards;
    Protection       prot = Protection::Public;
    commentScanner.parseCommentBlock(
        nullptr,
        &current,
        doc,          // text
        fileName(),   // file
        lineNr,       // line of block start
        false,        // isBrief
        false,        // isJavaDocStyle
        false,        // isInBody
        prot,         // protection
        pos,          // position,
        needsEntry,
        false,
        &guards
        );
    doc = current.doc;
  }
 
  // 8. add it as a page
  addRelatedPage(fileName(),theTranslator->trCiteReferences(),doc,fileName(),1,1);
 
  // 9. for latex we just copy the bib files to the output and let
  //    latex do this work.
  if (Config_getBool(GENERATE_LATEX))
  {
    // copy bib files to the latex output dir
    QCString latexOutputDir = Config_getString(LATEX_OUTPUT)+"/";
    i = 0;
    for (const auto &bibdata : citeDataList)
    {
      QCString bibFile = getBibFile(bibdata);
      FileInfo fi(bibFile.str());
      if (fi.exists())
      {
        if (!bibFile.isEmpty())
        {
          // bug_700510, multiple times the same name were overwriting; creating new names
          // also for names with spaces
          ++i;
          copyFile(bibFile,latexOutputDir + bibTmpFile + QCString().setNum(i) + ".bib");
        }
      }
      else
      {
        err("bib file {} not found!\n",bibFile);
      }
    }
  }
 
  // 10. Remove temporary files
  if (!citeDebug)
  {
    thisDir.remove(citeListFile.str());
    thisDir.remove(doxygenBstFile.str());
    thisDir.remove(bib2xhtmlFile.str());
    // we might try to remove too many files as empty files didn't get a corresponding new file
    // but the remove function does not emit an error for it and we don't catch the error return
    // so no problem.
    for (size_t j = 1; j <= citeDataList.size(); j++)
    {
      QCString bibFile = bibOutputDir + bibTmpFile + QCString().setNum(static_cast<int>(j)) + ".bib";
      thisDir.remove(bibFile.str());
    }
    thisDir.rmdir(bibOutputDir.str());
  }
}

References addRelatedPage(), bibTmpDir, bibTmpFile, Debug::Cite, Config_getBool, Config_getList, Config_getString, copyFile(), ResourceMgr::copyResource(), Dir::currentDirPath(), Entry::doc, err, Dir::exists(), FileInfo::exists(), FALSE, fileName(), QCString::find(), getBibFile(), getFormulas(), insertCrossReferencesForBibFile(), ResourceMgr::instance(), isEmpty(), QCString::isEmpty(), Debug::isFlagSet(), QCString::left(), QCString::length(), QCString::lower(), QCString::mid(), Dir::mkdir(), Portable::openInputStream(), Portable::openOutputStream(), p, CommentScanner::parseCommentBlock(), Dir::remove(), replaceFormulas(), QCString::right(), Dir::rmdir(), Dir::setCurrent(), QCString::setNum(), split(), QCString::str(), QCString::stripWhiteSpace(), Portable::system(), theTranslator, and TRUE.

Referenced by parseInput().

getFormulas()

QCString CitationManager::getFormulas ( const QCString & s )

private

Definition at line 236 of file cite.cpp.

{
  if (s.isEmpty()) return s;
  QCString result;
  result.reserve(s.length()+32);
  QCString formula;
  formula.reserve(256);
  bool insideFormula = false;
  int citeFormulaCnt = 1;
  const char *ps=s.data();
  char c = 0;
  while ((c=*ps++))
  {
    if (insideFormula)
    {
      switch (c)
      {
        case '\\':
          formula+=c;
          c = *ps++;
          formula+=c;
          break;
        case '\n':
          formula+=c;
          result+='$';
          result+=formula;
          insideFormula = false;
          formula.clear();
          break;
        case '$':
          {
            const size_t idLen = 30;
            char id[idLen];
            qsnprintf(id,idLen,"%s%06d",g_formulaMarker.c_str(),citeFormulaCnt);
            p->formulaCite.emplace(citeFormulaCnt,std::string("\\f$") + formula.str() + "\\f$");
            citeFormulaCnt++;
            // need { and } due to the capitalization rules of bibtex.
            result+='{';
            result+=id;
            result+='}';
            insideFormula = false;
            formula.clear();
          }
          break;
        default:
          formula+=c;
          break;
      }
    }
    else
    {
      switch (c)
      {
        case '\\':
          result+=c;
          c = *ps++;
          result+=c;
          break;
        case '$':
          insideFormula = true;
          break;
        default:
          result+=c;
          break;
      }
    }
  }
  if (insideFormula)
  {
    result+=formula;
    formula.clear();
  }
  return result;
}

References QCString::clear(), QCString::data(), g_formulaMarker, QCString::isEmpty(), QCString::length(), p, qsnprintf, QCString::reserve(), and QCString::str().

Referenced by generatePage(), and ~CitationManager().

insert()

void CitationManager::insert

(

const QCString &

label

)

Insert a citation identified by label into the database.

Definition at line 95 of file cite.cpp.

{
  QCString lowerCaseLabel = label.lower();
  p->entries.emplace(lowerCaseLabel.str(),std::make_unique<CiteInfoImpl>(lowerCaseLabel));
}

References QCString::lower(), p, and QCString::str().

Referenced by addCite(), and insertCrossReferencesForBibFile().

insertCrossReferencesForBibFile()

void CitationManager::insertCrossReferencesForBibFile ( const QCString & bibFile )

private

Definition at line 131 of file cite.cpp.

{
  // sanity checks
  if (bibFile.isEmpty())
  {
    return;
  }
  FileInfo fi(bibFile.str());
  if (!fi.exists())
  {
    err("bib file {} not found!\n",bibFile);
    return;
  }
  std::ifstream f = Portable::openInputStream(bibFile);
  if (!f.is_open())
  {
    err("could not open file {} for reading\n",bibFile);
    return;
  }
 
  // search for citation cross references
  QCString citeName;
 
  std::string lineStr;
  int lineCount = 0;
  while (getline(f,lineStr))
  {
    int i = -1;
    QCString line(lineStr);
    lineCount++;
    if (line.stripWhiteSpace().startsWith("@"))
    {
      // assumption entry like: "@book { name," or "@book { name" (spaces optional)
      int j = line.find('{');
      // when no {, go hunting for it
      while (j==-1 && getline(f,lineStr))
      {
        line = lineStr;
        lineCount++;
        j = line.find('{');
      }
      // search for the name
      citeName = "";
      if (!f.eof() && j!=-1) // to prevent something like "@manual ," and no { found
      {
        int k = line.find(',',j);
        j++;
        // found a line "@....{.....,...." or "@.....{....."
        //                     ^=j  ^=k               ^=j   k=-1
        while (!f.eof() && citeName.isEmpty())
        {
          if (k!=-1)
          {
            citeName = line.mid(static_cast<size_t>(j),static_cast<size_t>(k-j));
          }
          else
          {
            citeName = line.mid(static_cast<size_t>(j));
          }
          citeName = citeName.stripWhiteSpace();
          j = 0;
          if (citeName.isEmpty() && getline(f,lineStr))
          {
            line = lineStr;
            lineCount++;
            k = line.find(',');
          }
        }
      }
      //printf("citeName = #%s#\n",qPrint(citeName));
      if (!citeName.isEmpty())
      {
        std::string lCiteName = citeName.lower().str();
        auto it = p->citePosition.find(lCiteName);
        if (it != p->citePosition.end())
        {
          warn(bibFile,lineCount,"multiple use of citation name '{}', (first occurrence: {}, line {})",
               lCiteName,it->second.fileName,it->second.lineNr);
        }
        else
        {
          p->citePosition.emplace(lCiteName,CitePosition(bibFile,lineCount));
        }
      }
    }
    else if ((i=line.find("crossref"))!=-1 && !citeName.isEmpty()) /* assumption cross reference is on one line and the only item */
    {
      int j = line.find('{',i);
      int k = line.find('}',i);
      if (j>i && k>j)
      {
        QCString crossrefName = line.mid(static_cast<size_t>(j+1),static_cast<uint32_t>(k-j-1));
        // check if the reference with the cross reference is used
        // insert cross reference when cross reference has not yet been added.
        if (find(citeName) && !find(crossrefName)) // not found yet
        {
          insert(crossrefName);
        }
      }
    }
  }
}

References err, FileInfo::exists(), find(), QCString::find(), insert(), QCString::isEmpty(), lineCount, QCString::lower(), QCString::mid(), Portable::openInputStream(), p, QCString::startsWith(), QCString::str(), QCString::stripWhiteSpace(), and warn.

Referenced by generatePage(), and ~CitationManager().

instance()

CitationManager & CitationManager::instance ( )

static

Definition at line 85 of file cite.cpp.

{
  static CitationManager ct;
  return ct;
}

References CitationManager().

Referenced by addCite(), clearAll(), DocAnchor::DocAnchor(), DocCite::DocCite(), DocCite::getText(), LatexDocVisitor::operator()(), TextDocVisitor::operator()(), parseInput(), substituteLatexKeywords(), writeLatexMakefile(), and writeMakeBat().

isEmpty()

bool CitationManager::isEmpty

(

)

const

return TRUE if there are no citations.

Definition at line 115 of file cite.cpp.

{
  size_t numFiles = Config_getList(CITE_BIB_FILES).size();
  return (numFiles==0 || p->entries.empty());
}

References Config_getList, and p.

Referenced by generatePage(), substituteLatexKeywords(), writeLatexMakefile(), and writeMakeBat().

latexBibFiles()

QCString CitationManager::latexBibFiles

(

)

lists the bibtex cite files in a comma separated list

Definition at line 575 of file cite.cpp.

{
  QCString result;
  const StringVector &citeDataList = Config_getList(CITE_BIB_FILES);
  int i = 0;
  for (const auto &bibdata : citeDataList)
  {
    QCString bibFile = getBibFile(bibdata);
    FileInfo fi(bibFile.str());
    if (fi.exists() && !bibFile.isEmpty())
    {
      if (i) result += ",";
      i++;
      result += bibTmpFile;
      result += QCString().setNum(i);
    }
  }
  return result;
}

References bibTmpFile, Config_getList, FileInfo::exists(), getBibFile(), QCString::isEmpty(), QCString::setNum(), and QCString::str().

Referenced by substituteLatexKeywords().

replaceFormulas()

QCString CitationManager::replaceFormulas ( const QCString & s )

private

Definition at line 311 of file cite.cpp.

{
  if (s.isEmpty()) return s;
  QCString t;
  int pos=0;
  int i = -1;
  while ((i=s.find(g_formulaMarker,pos))!=-1)
  {
    t += s.mid(pos,i-pos);
    int markerSize = static_cast<int>( g_formulaMarker.length());
    int markerId = atoi(s.mid(i+markerSize,6).data());
    auto it = p->formulaCite.find(markerId);
    if (it != p->formulaCite.end()) t += it->second;
    pos = i + markerSize+6;
  }
  t += s.mid(pos);
  //printf("replaceFormulas(%s)=%s\n",qPrint(s),qPrint(t));
  return t;
}

References QCString::data(), QCString::find(), g_formulaMarker, QCString::isEmpty(), QCString::mid(), and p.

Referenced by generatePage(), and ~CitationManager().

Member Data Documentation

p

std::unique_ptr<Private> CitationManager::p

private

Definition at line 123 of file cite.h.

Referenced by CitationManager(), clear(), find(), generatePage(), getFormulas(), insert(), insertCrossReferencesForBibFile(), isEmpty(), and replaceFormulas().

---

The documentation for this class was generated from the following files:

• src/cite.h
• src/cite.cpp