FormulaManager Class Reference

#include <src/formula.h>

Classes
struct	Private

Public Member Functions
repository functions
void	initFromRepository (const QCString &dir)
void	checkRepositories ()
formula functions
void	clear ()
int	addFormula (const std::string &formulaText, int width=-1, int height=-1)
const Formula *	findFormula (int formulaId) const
bool	hasFormulas () const

Static Public Member Functions
static FormulaManager &	instance ()

Private Member Functions
void	createFormulasTexFile (Dir &d, Format format, HighDPI hd, Mode mode)
void	createLatexFile (const QCString &fileName, Format format, Mode mode, IntVector &formulasToGenerate)
	FormulaManager ()

Private Attributes
std::unique_ptr< Private >	p

generator functions
enum class	Format { Bitmap , Vector }
enum class	HighDPI { On , Off }
enum class	Mode { Dark , Light }
void	generateImages (const QCString &outputDir, Format format, HighDPI hd=HighDPI::Off)

Detailed Description

Manager class to handle formulas

Definition at line 58 of file formula.h.

Member Enumeration Documentation

Format

enum class FormulaManager::Format

strong

Enumerator
Bitmap
Vector

Definition at line 79 of file formula.h.

{ Bitmap, Vector };

HighDPI

enum class FormulaManager::HighDPI

strong

Enumerator
On
Off

Definition at line 80 of file formula.h.

{ On, Off };

Mode

enum class FormulaManager::Mode

strong

Enumerator
Dark
Light

Definition at line 81 of file formula.h.

{ Dark, Light };

Constructor & Destructor Documentation

FormulaManager()

FormulaManager::FormulaManager ( )

private

Definition at line 50 of file formula.cpp.

                               : p(std::make_unique<Private>())
{
}

References p.

Referenced by instance().

Member Function Documentation

addFormula()

int FormulaManager::addFormula	(	const std::string &	formulaText,
		int	width = -1,
		int	height = -1 )

Definition at line 691 of file formula.cpp.

{
  Formula *formula = p->formulas.find(formulaText);
  if (formula) // same formula already stored
  {
    return formula->id();
  }
  // add new formula
  int id = static_cast<int>(p->formulas.size());
  formula = p->formulas.add(formulaText.c_str(),id,width,height);
  p->formulaIdMap.emplace(id,formula);
  return id;
}

References Formula::id(), and p.

Referenced by addFormula().

checkRepositories()

void FormulaManager::checkRepositories

(

)

Definition at line 173 of file formula.cpp.

{
  //printf("checkRepositories valid=%d\n",p->repositoriesValid);
  if (!p->repositoriesValid)
  {
    clear(); // clear cached formulas, so the corresponding images and repository files
             // are regenerated
    p->repositoriesValid = true;
  }
}

References clear(), and p.

Referenced by parseInput().

clear()

void FormulaManager::clear

(

)

Definition at line 685 of file formula.cpp.

{
  p->formulas.clear();
  p->formulaIdMap.clear();
}

References p.

Referenced by checkRepositories(), cleanUpDoxygen(), and clearAll().

createFormulasTexFile()

void FormulaManager::createFormulasTexFile ( Dir & d, Format format, HighDPI hd, Mode mode )

private

Definition at line 553 of file formula.cpp.

{
  IntVector formulasToGenerate;
  QCString formulaFileName = mode==Mode::Light ? "_formulas" : "_formulas_dark";
  createLatexFile(formulaFileName,format,mode,formulasToGenerate);
 
  if (!formulasToGenerate.empty()) // there are new formulas
  {
    if (!createDVIFile(formulaFileName)) return;
 
    auto getFormula = [this](int pageNum) -> Formula *
    {
      auto it = p->formulaIdMap.find(pageNum);
      if (it!=p->formulaIdMap.end())
      {
        return it->second;
      }
      return nullptr;
    };
 
    int pageIndex=1;
    std::size_t numThreads = static_cast<std::size_t>(Config_getInt(NUM_PROC_THREADS));
    if (numThreads>1) // multi-threaded version
    {
      ThreadPool threadPool(numThreads);
      std::vector< std::future< StringVector > > results;
      for (int pageNum : formulasToGenerate)
      {
        // create images for each formula.
        auto formula = getFormula(pageNum);
        auto processFormula = [=]() -> StringVector
        {
          return generateFormula(thisDir,formulaFileName,formula,pageNum,pageIndex,format,hd,mode);
        };
        results.emplace_back(threadPool.queue(processFormula));
        pageIndex++;
      }
      for (auto &f : results)
      {
        auto tf = f.get();
        p->tempFiles.insert(p->tempFiles.end(),tf.begin(),tf.end()); // append tf to p->tempFiles
      }
    }
    else // single threaded version
    {
      for (int pageNum : formulasToGenerate)
      {
        // create images for each formula.
        auto formula = getFormula(pageNum);
        StringVector tf = generateFormula(thisDir,formulaFileName,formula,pageNum,pageIndex,format,hd,mode);
        p->tempFiles.insert(p->tempFiles.end(),tf.begin(),tf.end()); // append tf to p->tempFiles
 
        pageIndex++;
      }
    }
    // remove intermediate files produced by latex
    p->tempFiles.push_back(formulaFileName.str()+".dvi");
    p->tempFiles.push_back(formulaFileName.str()+".log");
    p->tempFiles.push_back(formulaFileName.str()+".aux");
  }
  // remove the latex file itself
  p->tempFiles.push_back(formulaFileName.str()+".tex");
 
  // write/update the formula repository so we know what text the
  // generated images represent (we use this next time to avoid regeneration
  // of the images, and to avoid forcing the user to delete all images in order
  // to let a browser refresh the images).
  std::ofstream f = Portable::openOutputStream("formula.repository");
  if (f.is_open())
  {
    TextStream t(&f);
    for (const auto &formula : p->formulas)
    {
      t << "\\_form#" << formula->id();
      if (formula->width()!=-1 && formula->height()!=-1)
      {
        t << "=" << formula->width() << "x" << formula->height();
      }
      t << ":" << formula->text() << "\n";
    }
  }
}

References Config_getInt, createDVIFile(), createLatexFile(), generateFormula(), Light, Portable::openOutputStream(), p, ThreadPool::queue(), and QCString::str().

Referenced by generateImages().

createLatexFile()

void FormulaManager::createLatexFile ( const QCString & fileName, Format format, Mode mode, IntVector & formulasToGenerate )

private

Definition at line 184 of file formula.cpp.

{
  // generate a latex file containing one formula per page.
  QCString texName=fileName+".tex";
  std::ofstream f = Portable::openOutputStream(texName);
  if (f.is_open())
  {
    TextStream t(&f);
    t << "\\documentclass{article}\n";
    t << "\\usepackage{iftex}\n";
    t << "\\usepackage{ifthen}\n";
    t << "\\usepackage{epsfig}\n"; // for those who want to include images
    t << "\\usepackage[utf8]{inputenc}\n"; // looks like some older distributions with newunicode package 1.1 need this option.
    t << "\\usepackage{xcolor}\n";
 
    if (mode==Mode::Dark) // invert page and text colors
    {
      t << "\\color{white}\n";
      t << "\\pagecolor{black}\n";
    }
 
    writeExtraLatexPackages(t);
    writeLatexSpecialFormulaChars(t);
 
    QCString macroFile = Config_getString(FORMULA_MACROFILE);
    if (!macroFile.isEmpty())
    {
      FileInfo fi(macroFile.str());
      QCString stripMacroFile = fi.fileName();
      t << "\\input{" << stripMacroFile << "}\n";
    }
 
    t << "\\pagestyle{empty}\n";
    t << "\\begin{document}\n";
    for (const auto &formula : p->formulas)
    {
      int id = formula->id();
      // only formulas for which no image is cached are generated
      //printf("check formula %d: cached=%d cachedDark=%d\n",formula->id(),formula->isCached(),formula->isCachedDark());
      if ((mode==Mode::Light && !formula->isCached()) ||
          (mode==Mode::Dark && !formula->isCachedDark())
         )
      {
        // we force a pagebreak after each formula
        t << formula->text() << "\n\\pagebreak\n\n";
        formulasToGenerate.push_back(id);
      }
      QCString resultName;
      resultName.sprintf("form_%d%s.%s",id, mode==Mode::Light?"":"_dark", format==Format::Vector?"svg":"png");
      Doxygen::indexList->addImageFile(resultName);
    }
    t << "\\end{document}\n";
    t.flush();
    f.close();
  }
}

References Config_getString, Dark, FileInfo::fileName(), TextStream::flush(), Doxygen::indexList, QCString::isEmpty(), Light, Portable::openOutputStream(), p, QCString::sprintf(), QCString::str(), Vector, writeExtraLatexPackages(), and writeLatexSpecialFormulaChars().

Referenced by createFormulasTexFile().

findFormula()

const Formula * FormulaManager::findFormula

(

int

formulaId

)

const

Definition at line 705 of file formula.cpp.

{
  auto   it  = p->formulaIdMap.find(formulaId);
  return it != p->formulaIdMap.end() ? it->second : nullptr;
}

References p.

Referenced by DocFormula::DocFormula(), and HtmlDocVisitor::operator()().

generateImages()

void FormulaManager::generateImages	(	const QCString &	outputDir,
		Format	format,
		HighDPI	hd = HighDPI::Off )

Definition at line 636 of file formula.cpp.

{
  Dir d(path.str());
  // store the original directory
  if (!d.exists())
  {
    term("Output directory '%s' does not exist!\n",qPrint(path));
  }
  std::string oldDir = Dir::currentDirPath();
 
  QCString macroFile = Config_getString(FORMULA_MACROFILE);
  QCString stripMacroFile;
  if (!macroFile.isEmpty())
  {
    FileInfo fi(macroFile.str());
    macroFile=fi.absFilePath();
    stripMacroFile = fi.fileName();
  }
 
  // go to the html output directory (i.e. path)
  Dir::setCurrent(d.absPath());
  Dir thisDir;
 
  if (!macroFile.isEmpty())
  {
    copyFile(macroFile,stripMacroFile);
  }
 
  createFormulasTexFile(thisDir,format,hd,Mode::Light);
  if (Config_getEnum(HTML_COLORSTYLE)!=HTML_COLORSTYLE_t::LIGHT) // all modes other than light need a dark version
  {
    // note that the dark version reuses the bounding box of the light version so it needs to be
    // created after the light version.
    createFormulasTexFile(thisDir,format,hd,Mode::Dark);
  }
 
  // clean up temporary files
  if (!Debug::isFlagSet(Debug::Formula))
  {
    for (const auto &file : p->tempFiles)
    {
      thisDir.remove(file);
    }
  }
 
  // reset the directory to the original location.
  Dir::setCurrent(oldDir);
}

References FileInfo::absFilePath(), Dir::absPath(), Config_getEnum, Config_getString, copyFile(), createFormulasTexFile(), Dir::currentDirPath(), Dark, Dir::exists(), FileInfo::fileName(), Debug::Formula, QCString::isEmpty(), Debug::isFlagSet(), Light, p, qPrint(), Dir::remove(), Dir::setCurrent(), QCString::str(), and term.

Referenced by generateOutput().

hasFormulas()

bool FormulaManager::hasFormulas

(

)

const

Definition at line 720 of file formula.cpp.

{
  return !p->formulas.empty();
}

References p.

Referenced by generateOutput().

initFromRepository()

void FormulaManager::initFromRepository

(

const QCString &

dir

)

Definition at line 60 of file formula.cpp.

{
  std::ifstream f = Portable::openInputStream(dir+"/formula.repository");
  if (f.is_open())
  {
    uint32_t formulaCount=0;
    msg("Reading formula repository...\n");
    std::string readLine;
    std::string line;
    std::string prefix("\\_form#");
    int nextLineNr=1;
    bool hasNextLine = !getline(f,readLine).fail();
    while (hasNextLine)
    {
      line = readLine;
      int lineNr = nextLineNr;
 
      // look ahead a bit because a formula can be spread over several lines
      while ((hasNextLine = !getline(f,readLine).fail()))
      {
        nextLineNr+=1;
        if (!readLine.compare(0, prefix.size(), prefix)) break;
        line += "\n" + readLine;
      }
 
      // new format: \_form#<digits>=<digits>x<digits>:formula
      static const reg::Ex re_new(R"(\\_form#(\d+)=(\d+)x(\d+):)");
      // old format: \_form#<digits>:formula
      static const reg::Ex re_old(R"(\\_form#(\d+):)");
 
      reg::Match match;
      int id     = -1;
      int width  = -1;
      int height = -1;
      std::string text;
      if (reg::search(line,match,re_new)) // try new format first
      {
        id     = std::stoi(match[1].str());
        width  = std::stoi(match[2].str());
        height = std::stoi(match[3].str());
        text   = line.substr(match.position()+match.length());
        //printf("new format found id=%d width=%d height=%d text=%s\n",id,width,height,text.c_str());
      }
      else if (reg::search(line,match,re_old)) // check for old format
      {
        //id     = std::stoi(match[1].str());
        //text   = line.substr(match.position()+match.length());
        //printf("old format found id=%d text=%s\n",id,text.c_str());
        msg("old formula.repository format detected; forcing upgrade.\n");
        p->repositoriesValid = false;
        break;
      }
      else // unexpected content
      {
        warn_uncond("%s/formula.repository contains invalid content at line %d: found: '%s'\n",qPrint(dir),lineNr,line.c_str());
        p->repositoriesValid = false;
        break;
      }
 
      auto it = p->formulaIdMap.find(id);
      Formula *formula=nullptr;
      if (it!=p->formulaIdMap.end()) // formula already found in a repository for another output format
      {
        formula = it->second;
        if (formula->text().str()!=text) // inconsistency between repositories detected
        {
          msg("differences detected between formula.repository files; forcing upgrade.\n");
          p->repositoriesValid = false;
          break;
        }
        formulaCount++;
      }
      else // create new formula from cache
      {
        //printf("formula not found adding it under id=%d\n",id);
        formula = p->formulas.add(text.c_str(),id,width,height);
        p->formulaIdMap.emplace(id,formula);
      }
 
      if (formula) // if an entry in the repository exists also check if there is a generated image
      {
        QCString formImgName;
        formImgName.sprintf("form_%d",formula->id());
        FileInfo fiPng((dir+"/"+formImgName+".png").str());
        FileInfo fiSvg((dir+"/"+formImgName+".svg").str());
        // mark formula as cached, so we do not need to regenerate the images
        bool isCached = fiPng.exists() || fiSvg.exists();
        formula->setCached(isCached);
        //printf("formula %d: cached=%d\n",formula->id(),isCached);
 
        FileInfo fiPngDark((dir+"/"+formImgName+"_dark.png").str());
        FileInfo fiSvgDark((dir+"/"+formImgName+"_dark.svg").str());
        bool isCachedDark = fiPngDark.exists() || fiSvgDark.exists();
        formula->setCachedDark(isCachedDark);
        //printf("formula %d: cachedDark=%d\n",formula->id(),isCachedDark);
      }
    }
 
    // For the first repository all formulas should be new (e.g. formulaCount==0).
    // For the other repositories the same number of formulas should be found
    // (and number of formulas should be the same for all repositories, content is already check above)
    if (formulaCount>0 && formulaCount!=p->formulas.size()) // inconsistency between repositories
    {
      msg("differences detected between formula.repository files; forcing upgrade.\n");
      p->repositoriesValid = false;
    }
  }
  else // no repository found for an output format
  {
    p->repositoriesValid = false;
  }
}

References FileInfo::exists(), Formula::id(), msg(), Portable::openInputStream(), p, prefix, qPrint(), reg::search(), Formula::setCached(), Formula::setCachedDark(), QCString::sprintf(), QCString::str(), Formula::text(), and warn_uncond.

Referenced by parseInput().

instance()

FormulaManager & FormulaManager::instance ( )

static

Definition at line 54 of file formula.cpp.

{
  static FormulaManager fm;
  return fm;
}

References FormulaManager().

Referenced by addFormula(), cleanUpDoxygen(), clearAll(), DocFormula::DocFormula(), generateOutput(), HtmlDocVisitor::operator()(), and parseInput().

Member Data Documentation

p

std::unique_ptr<Private> FormulaManager::p

private

Definition at line 90 of file formula.h.

Referenced by addFormula(), checkRepositories(), clear(), createFormulasTexFile(), createLatexFile(), findFormula(), FormulaManager(), generateImages(), hasFormulas(), and initFromRepository().

---

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

• src/formula.h
• src/formula.cpp