dxl.cpp

//==================================================================================================
// This implementation-file is part of DoxygenXLinks - A doxygen post-processor that allows to
// define smarter <b>Doxygen</b>-links.
//
// \emoji :copyright: 2025-2026 A-Worx GmbH, Germany.
// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#include "dxl.hpp"
#include "index.hpp"
#include "jobs.hpp"
#include "dxlapp.hpp"
#include "doxyfile.hpp"
#include "expressions.hpp"
#include "ALib.ALox.Impl.H"
#include "ALib.App.CLI.H"
#include "ALib.Files.H"
#include "ALib.System.H"
#include "ALib.Format.FormatterPythonStyle.H"
 
using namespace alib;
 
namespace dxl {
// todo: beim matchen später, wenn er nix findet, die filenames durchsuchen, ob es hier
//       einen treffer per substring gibt. Dann als link display den vollen filenamen
//       einsetzen. Dies würde die \implude rauswerfen und man könnte komplett verkürzte
//       filenamen benutzen.
// todo: Alle stellen suchen wo fixe Werte zur optimierung stehen: Stack size, String length
//       number of arguments, etc. und
//       [ ] mit konstanten ersetzen
//       [ ] Exceptions einbauen: ArgumentOverflow, CompoundNestingOverflow, etc.
// todo: Das doxygen macro alibcppfile linked direkt in das HTML eines cpp file. Wieso ist das so?
//       Was hab ich da gemacht? Wenn es doch von doxygen als HTML angelegt wird, sollte es doch
//       auch im tag-file auftauchen. Tut es aber (glaube ich) nicht.
// todo: in der ALib Doku tauchen noch "/home/dev/A-Worx/ALib", z.B. in Snippets, auf. Also muss es hier noch
//       eine Möglichkeit geben in den HTML Datein search & replace zu machen. Als Nebentätigkeit
//       dieses tools.
// todo: Im Tagfile steht im Typ of "ALIB_DLL". Das müsste eigentlich mit anpassen des Doxyfiles
//       Bzgl. der Macros rauszubekommen sein. Ansonsten auch hier ein Search/Replace anbieten.
 
#if ALIB_DEBUG
extern void DbgUnitTests(DoxygenXLinks*);
#endif
// #################################################################################################
// Tools
// #################################################################################################
#include "ALib.Lang.CIFunctions.H"
 
namespace {
struct DLHTMLFileFilter : files::FFilter {
    String &extension;
 
    DLHTMLFileFilter(String &ext) : extension(ext) {}
 
    bool Includes(const File &file, const system::PathString &) override {
        return file.Name().EndsWith<CHK, lang::Case::Ignore>(extension);
    }
};
 
struct DLSrcFileFilter : files::FFilter {
    DoxygenINIFile &doxyfile;
 
    DLSrcFileFilter(DoxygenINIFile &df) : doxyfile(df) {}
 
    bool Includes(const File &file, const system::PathString &) override {
        String64 extension(file.Name().Substring(file.Name().LastIndexOf('.')));
        if (doxyfile.FilePatterns.IndexOf(extension) < 0)
            return false;
 
        return true;
    }
};
 
struct RecentlyModifiedFirst : StringTreeIterator<FTree>::Sorter {
    bool Compare(const FTree::ConstCursor &lhs, const FTree::ConstCursor &rhs) override {
        // Prefer directories over files.
        if (lhs.CountChildren() == 0 && rhs.CountChildren() != 0) return false;
        if (lhs.CountChildren() != 0 && rhs.CountChildren() == 0) return true;
 
        // Sort by modification date.
        return lhs->MDate() > rhs->MDate();
    }
};
 
String htmlConversionCodes[] = {
    "lt;"      ,
    "gt;"      ,
    "amp;"     ,
    "apos;"    ,
    "lsqb;"    ,
    "rsqb;"    ,
    "commat;"  ,
    "dollar;"  ,
    "nbsp;"    ,
    "quot;"     // // We keep "&quot;" in when converting html -> ASCII
};
constexpr String htmlConversionChars ="<>&'[]@$ \"";
 
 
}
 
#include "ALib.Lang.CIMethods.H"
 
 
void ConvertHTMLEntitiesToAscii(alib::AString &buffer) {
    String4K replacement;
    //replacement.DbgDisableBufferReplacementWarning()
    bool replacementFound= false;
    for (integer idx= 0; idx < buffer.Length() ; ++idx ) {
        nchar c= buffer.CharAt(idx);
        if ( c != '&' )
            replacement._(c);
        else {
            String actBuf= buffer.Substring(idx+1);
            integer codeIdx= 0;
            // loop over code table, except the last one "quot;". That's kept in
            for (; codeIdx< integer(sizeof(htmlConversionCodes)/sizeof(String)) -1; ++codeIdx) {
                if ( actBuf.StartsWith(htmlConversionCodes[codeIdx]) ) {
                    replacement._(htmlConversionChars.CharAt(codeIdx));
                    idx+= htmlConversionCodes[codeIdx].Length();
                    replacementFound= true;
                    break;
                }
            }
            if ( codeIdx == sizeof(htmlConversionCodes)/sizeof(String) )
                replacement._('&');
        }
    }
    if (replacementFound)
        buffer.Reset(replacement);
 
}
 
void ConvertASCIItoHTMLEntities(alib::AString &buffer) {
    String4K replacement;
    //replacement.DbgDisableBufferReplacementWarning()
    bool replacementFound= false;
    for (auto c : buffer ) {
        integer idx= htmlConversionChars.IndexOf(c);
        if ( idx < 0 )
            replacement._(c);
        else {
            replacement._('&')._<NC>(htmlConversionCodes[idx]);
            replacementFound= true;
        }
    }
    if (replacementFound)
        buffer.Reset(replacement);
}
 
// #############################################################################################
// DoxygenXLinks
// #################################################################################################
DoxygenXLinks::DoxygenXLinks()
: fTreeSources(16)
, fTreeHTML(16)
, MA(ALIB_DBG("DLMain",) 1024)
, Doxyfile{MA}
, XLinkMap{MA}
, Indices{MA}
{
    ALIB_DBG(DLLock.Dbg.Name= "DL::MALock";)
}
 
 
DoxygenXLinks::~DoxygenXLinks() {
    if (!TPool.IsIdle()) {
        Lox_Warning("Destructing DoxygenXLinks while not idle.")
        TPool.WaitForAllIdle(5s ALIB_DBG(, 1s));
        if (!TPool.IsIdle())
            Lox_Error("DoxygenXLinks not idle after 5s. destructing nevertheless now.")
    } else
        Lox_Verbose("{} is idle, shutting it down.", TPool)
 
    TPool.Shutdown();
    for (auto* index: Indices)
        lang::Destruct(*index);
}
 
void DoxygenXLinks::AddAnchorTitle( const String& anchorName, const String& anchorTitle,
                                    const String& sourceHint  ) {
    // search anchor in  indices
    for (auto* index: Indices)
        {ALIB_LOCK_SHARED_WITH(index->SLock)
            for (   auto range= index->entityMap.EqualRange(anchorName)
                  ; range.first!=range.second
                  ; ++range.first) {
 
                if ( auto* docAnchor= static_cast<TGTDocAnchor*>(index->ImportCursor(range.first->second).Value());
                    docAnchor && docAnchor->Title.IsEmpty() ) {
                    docAnchor->Title= String(index->ma, anchorTitle);
                    Lox_Info("XTRA", "Added title to anchor {!Q} of tag-file {!Q}\n"
                                     "   Anchor source: {}\n"
                                     "   Anchor title:  {!Q}"
                               , anchorName, index->FileName, sourceHint, anchorTitle )
                    return;
                }
            }
        }
    Lox_Info("XTRA", "Title for anchor {!Q} hinted, but anchor not found in tag-files\n"
                     "   Anchor source: {}\n"
                     "   Anchor title:  {!Q}"
               , anchorName, sourceHint, anchorTitle )
}
 
void DoxygenXLinks::scanHTMLFiles() {
    Lox_SetDomain("/DXL/SCAN/HTML", Scope::Method)
    Lox_Info("Scanning HTML-files...")
 
    /// Scan parameters used when scanning the HTML-input-files, as well as the source files.
 
    Lox_Info("Scanning Doxygen's output folder and launching read jobs on HTML input files.\n"
             "   Maximum depth {}, File extension {!Q}, Doxygen output directory {!Q}"
           , Doxyfile.HtmlSubfolderDepth
           , Doxyfile.HtmlFileExtension
           , Doxyfile.HTMLFilePath)
 
    files::ScanParameters htmlScanParams(Doxyfile.HTMLFilePath,
                                         ScanParameters::SymbolicLinks::RECURSIVE,
                                         Doxyfile.HtmlSubfolderDepth + 1,
                                         true,  // crossFileSystems
                                         true); // IncludeArtificialFS
    htmlScanParams.FileFilter = SPFileFilter(new DLHTMLFileFilter(Doxyfile.HtmlFileExtension));
    files::CanonicalPathList resultPaths;
    auto scanResult= alib::files::ScanFiles(*fTreeHTML, htmlScanParams, &resultPaths);
    if (    scanResult == FInfo::ScanStates::NOT_EXISTENT
         || resultPaths.empty()
         || resultPaths.front().IsInvalid() ) {
        DXLApp &app = app::Get<DXLApp>();
        app.cErr->Add(app.cli.ExitCodeDecls.Find(ExitCodes::NoHTMLFilesFound).Mapped()->
                          FormatString(),
                      Doxyfile.HtmlFileExtension, Doxyfile.HTMLFilePath);
        app.machine.SetExitCode(ExitCodes::NoHTMLFilesFound);
        throw Exception(ALIB_CALLER_NULLED, app::App::Exceptions::ControlledEarlyExit);
    }
 
    Lox_Info("HTML file tree scanned.") {
        int cntLoggers;
        Lox_IsActive(cntLoggers, Verbosity::Verbose)
        if (cntLoggers > 0) {
            String64 buf;
            buf.DbgDisableBufferReplacementWarning(); {
                ALIB_LOCK_SHARED_WITH(fTreeHTML)
                ALIB_DBG(files::DbgDump(buf, *fTreeHTML);)
                // todo: this method is not available in release builds, hence, .
            } //       it has to be done here on our own
            Lox_Prune(TextLogger* rlogger= app::Get().GetRLogger();
                      rlogger->GetFormatMultiLine().Mode=3;)
            Lox_Verbose("File tree:")
            Lox_Verbose(buf)
            Lox_Prune(rlogger->GetFormatMultiLine().Mode=2;)
        }
    }
}
 
void DoxygenXLinks::schduleHTMLReplacers() {
    Lox_SetDomain("/DXL/SCAN/HTML", Scope::Method)
    Lox_Info("Scheduling HTMLReplacer jobs")
    // we want maximum speed and even spare the fast log calls in the loop.
    Verbosity verbosity;
    Lox_GetVerbosity(verbosity)
 
    ALIB_LOCK_SHARED_WITH(GetHTMLTreeLock())
    StringTreeIterator<FTree> treeIt;
    treeIt.Initialize(fTreeHTML->Root().AsCursor(), lang::Inclusion::Exclude);
    String32 omitSourceHTMLs("_source");
             omitSourceHTMLs << Doxyfile.HtmlFileExtension;
 
    while (treeIt.IsValid()) {
        if (     !treeIt.Node()->IsDirectory()
             &&  !treeIt.Node().Name().EndsWith(omitSourceHTMLs) ) {
 
            if (verbosity >= Verbosity::Info)
                Lox_Info("Scheduling XLink replacement on HTML-file {!Q}", TPool, treeIt.Node().Name())
            TPool.ScheduleVoid<HTMLReplacer>(*this, treeIt.Node());
            Stats.HTMLFiles.fetch_add(1);
        }
 
        treeIt.Next();
    }
 
    auto qtyFiles = Stats.HTMLFiles.load();
    if (qtyFiles == 0) {
        DXLApp &app = app::Get<DXLApp>();
        app.cErr->Add(app.cli.ExitCodeDecls.Find(ExitCodes::NoHTMLFilesFound).Mapped()->
                          FormatString(),
                      Doxyfile.HtmlFileExtension, Doxyfile.HTMLFilePath);
        app.machine.SetExitCode(ExitCodes::NoHTMLFilesFound);
        throw Exception(ALIB_CALLER_NULLED, app::App::Exceptions::ControlledEarlyExit);
    }
 
 
}
 
void DoxygenXLinks::scanSrcFiles() {
    Lox_SetDomain("/DXL/SCAN/SRC", Scope::Method)
 
    Lox_Info("Scanning Doxygen's input folders (sources).\n"
             "   Maximum depth {}, File extensions {!Q}"
           , Doxyfile.RecursiveInputScan ? ScanParameters::InfiniteRecursion : 1
           , Doxyfile.FilePatterns)
    for (auto it: Doxyfile.InputPaths)      Lox_Info("   Input path      {}", it)
    for (auto it: Doxyfile.ExcludePaths)    Lox_Info("   Exclude path    {}", it)
    for (auto it: Doxyfile.ExcludePatterns) Lox_Info("   Exclude pattern {}", it)
 
    SPFileFilter FileFilter(new DLSrcFileFilter(Doxyfile));
 
    files::CanonicalPathList resultPaths;
    for (auto it: Doxyfile.InputPaths) {
        Path scanPath(it);
        if(!scanPath.IsAbsolute()) {
            scanPath.InsertAt("/", 0);
            scanPath.InsertAt(app::Get<DXLApp>().PWD, 0);
        }
 
        files::ScanParameters srcScanParams(scanPath,
                                            ScanParameters::SymbolicLinks::RECURSIVE,
                                            Doxyfile.RecursiveInputScan ? ScanParameters::InfiniteRecursion : 1,
                                            true,  // crossFileSystems
                                            true); // IncludeArtificialFS
        srcScanParams.FileFilter = FileFilter;
        alib::files::ScanFiles(*fTreeSources, srcScanParams, &resultPaths);
    }
 
    Lox_Info("Source file tree scanned.") {
        int cntLoggers;
        Lox_IsActive(cntLoggers, Verbosity::Verbose)
        if (cntLoggers > 0) {
            String64 buf;
            buf.DbgDisableBufferReplacementWarning();
            {ALIB_LOCK_SHARED_WITH(fTreeSources)
                ALIB_DBG(files::DbgDump(buf, *fTreeSources);)
                // todo: this method is not available in release builds, hence, .
            }   //       it has to be done here on our own
            Lox_Prune(TextLogger* rlogger= app::Get().GetRLogger();
                      rlogger->GetFormatMultiLine().Mode=3;)
            Lox_Verbose("File tree:")
            Lox_Verbose(buf)
            Lox_Prune(rlogger->GetFormatMultiLine().Mode=2;)
        }
    }
}
 
void DoxygenXLinks::scheduleSrcScanners() {
    Lox_SetDomain("/DXL/SCAN/SRC", Scope::Method)
    Lox_Info("Scheduling source scanner jobs")
 
    // we want maximum speed and even spare the fast log calls in the loop.
    Verbosity verbosity;
    Lox_GetVerbosity(verbosity)
 
    ALIB_LOCK_SHARED_WITH(GetSourceTreeLock())
    StringTreeIterator<FTree> treeIt;
    treeIt.Initialize(fTreeSources->Root().AsCursor(), lang::Inclusion::Exclude);
 
    while (treeIt.IsValid()) {
        if ( !treeIt.Node()->IsDirectory() ) {
 
            if (verbosity >= Verbosity::Info)
                Lox_Info("Scheduling XLink search on source-file {!Q}", treeIt.Node().Name())
            TPool.ScheduleVoid<SourceLocationFinder>(*this, treeIt.Node());
            Stats.SourceFiles.fetch_add(1);
        }
 
        treeIt.Next();
    }
 
    auto qtyFiles = Stats.SourceFiles.load();
    if (qtyFiles == 0) {
        DXLApp &app = app::Get<DXLApp>();
        app.cErr->Add(app.cli.ExitCodeDecls.Find(ExitCodes::NoSourceFilesFound).Mapped()->
                          FormatString());
        app.machine.SetExitCode(ExitCodes::NoSourceFilesFound);
        throw Exception(ALIB_CALLER_NULLED, app::App::Exceptions::ControlledEarlyExit);
    }
}
 
 
void DoxygenXLinks::scanReplSrcFiles(const alib::String& folder) {
    Lox_SetDomain("/DXL/SCAN/SRCREPL", Scope::Method)
    {ALIB_LOCK_WITH(GetSourceTreeLock()) fTreeSources->DeleteAllCustomData<XLinkList>();
                                          fTreeSources.Reset();                              }
 
    Path scanPath(folder);
    if(!scanPath.IsAbsolute()) {
        scanPath.InsertAt("/", 0);
        scanPath.InsertAt(app::Get<DXLApp>().PWD, 0);
    }
 
    Lox_Info("Scanning source copies in directory {}", folder )
    files::CanonicalPathList resultPaths;
    files::ScanParameters srcScanParams( scanPath,
                                         ScanParameters::SymbolicLinks::RECURSIVE,
                                         ScanParameters::InfiniteRecursion,
                                         true,  // crossFileSystems
                                         true); // IncludeArtificialFS
    {ALIB_LOCK_WITH(fTreeSources.GetLock())
       alib::files::ScanFiles(*fTreeSources, srcScanParams, &resultPaths); }
 
 
    Lox_Info("Source copies file tree scanned.") {
        int cntLoggers;
        Lox_IsActive(cntLoggers, Verbosity::Verbose)
        if (cntLoggers > 0) {
            String64 buf;
            buf.DbgDisableBufferReplacementWarning();
            {ALIB_LOCK_SHARED_WITH(fTreeSources)
                ALIB_DBG(files::DbgDump(buf, *fTreeSources);)
                // todo: this method is not available in release builds, hence, .
            }   //       it has to be done here on our own
            Lox_Prune(TextLogger* rlogger= app::Get().GetRLogger();
                      rlogger->GetFormatMultiLine().Mode=3;)
            Lox_Verbose("File tree:")
            Lox_Verbose(buf)
            Lox_Prune(rlogger->GetFormatMultiLine().Mode=2;)
        }
    }
}
 
void DoxygenXLinks::schduleSourceReplacers(const alib::String& folder) {
    Lox_SetDomain("/DXL/SCAN/SRCREPL", Scope::Method)
    Lox_Info("Scheduling source replacer jobs")
 
    // we want maximum speed and even spare the fast log calls in the loop.
    Verbosity verbosity;
    Lox_GetVerbosity(verbosity)
 
    ALIB_LOCK_SHARED_WITH(GetSourceTreeLock())
    StringTreeIterator<FTree> treeIt;
    treeIt.Initialize(fTreeSources->Root().AsCursor(), lang::Inclusion::Exclude);
 
    while (treeIt.IsValid()) {
        if ( !treeIt.Node()->IsDirectory() ) {
 
            if (verbosity >= Verbosity::Info) {
                Path p; File(treeIt.Node()).AssembleSymbolicPath(p, lang::Inclusion::Include);
                Lox_Info("Scheduling XLink-replacement on source-copy {!Q}", p)
            }
            TPool.ScheduleVoid<SourceReplacer>(*this, treeIt.Node());
            Stats.ReplSourceFiles.fetch_add(1);
        }
 
        treeIt.Next();
    }
 
    auto qtyFiles = Stats.ReplSourceFiles.load();
    if (qtyFiles == 0) {
        DXLApp &app = app::Get<DXLApp>();
        app.cErr->Add(app.cli.ExitCodeDecls.Find(ExitCodes::NoSourceCopiesFound).Mapped()->
                          FormatString(), folder);
        app.machine.SetExitCode(ExitCodes::NoSourceCopiesFound);
        throw Exception(ALIB_CALLER_NULLED, app::App::Exceptions::ControlledEarlyExit);
    }
}
 
//==================================================================================================
// Run
//==================================================================================================
void DoxygenXLinks::Run() {
 
 
    DXLApp &app = app::Get<DXLApp>();
    Lox_SetDomain("DXL", Scope::Filename)
    auto* rlogger = app.GetRLogger();
    Lox_SetVerbosity(rlogger, Verbosity::Info, "/")
    Lox_SetVerbosity(rlogger, Verbosity::Warning, "/ALIB/FILES")
    Lox_SetVerbosity(rlogger, Verbosity::Warning, "/ALIB/TMOD")
    Lox_SetVerbosity(rlogger, Verbosity::Warning, "/ALIB/TMOD")
    Lox_SetVerbosity(rlogger, Verbosity::Warning, "$/")
    Lox_SetVerbosity(rlogger, Verbosity::Warning, "$/V")
 
    Lox_Info("{} {}: Started", app.GetName(), app.GetVersion())
    Lox_Verbose(app.GetInfo())
 
    Lox_Info("Number of hardware-threads (machine spec): ", std::thread::hardware_concurrency())
 
    dynamic_cast<format::FormatterPythonStyle&>(*app.cOut->Formatter).Sizes
                                        ->Actual(AutoSizes::Types::Tabstop, 25, 0);
    app.printConfigFileInfo(*app.cOut);
 
    // read current directory, if given. Otherwise detect
    Variable pwd= variables::CampVariable(alib::APPCLI_CAMP, A_CHAR("WORKING_DIR"), A_CHAR("S") );
    if(pwd.Define()) {
        Path currentDir(SystemFolders::Current);
        pwd.GetString().Reset(currentDir);
        Lox_Warning("Current directory detected as: ", pwd.GetString())
    }
    else Lox_Warning("Current directory provided with parameter --PWD={}", pwd.GetString())
    app.PWD= pwd.GetString();
 
    app.cOut->Add("Doxyfile: {!ATab}:1", app.DoxyfilePath);
    Doxyfile.Load(app.DoxyfilePath);
    // todo: This should be a command or option. If command, exit afterwards.
    //       If option, continue processing.
    // todo: The Dump function has to be checked to be up to date.
    //Doxyfile.Dump();
 
    // read exclamation file
    app.cOut->Add("Exclamations-file:  {!ATab}:1", ExclamationsPath);
    app.onSdOutput();
    Exclamations.Read(ExclamationsPath);
 
    // configure the thread pool
    // todo: make configurable. Probably a general App-Variable which allows to specifiy the
    // most important settings of class ThreadPool?
    TPool.Strategy.Mode = ThreadPool::ResizeStrategy::Modes::Fixed;
    TPool.Strategy.WorkersMax=10;
    TPool.Strategy.WorkersMax= 1;
    Lox_Info("Schedule file scan...")
 
    // scan source- and html-files
    fTreeSources.DbgCriticalSections(lang::Switch::Off);
    fTreeHTML   .DbgCriticalSections(lang::Switch::Off);
    scanSrcFiles();    // This launches the SourceLocationFinder jobs
    scanHTMLFiles();   // This does NOT launch the HTMLReplacer jobs.
 
    // read Doxygen tag-file and create index
    app.stopWatch.Sample();
 
    {ALIB_LOCK_WITH(DLLock)
     Indices.reserve(size_t(Doxyfile.TagFiles.size())); }
 
    /// ----- multithreading starts here ----
    ALIB_DBG( MA.DbgCriticalSectionsPH->DCSLock= &DLLock; )
    fTreeSources.DbgCriticalSections(lang::Switch::On);
    fTreeHTML   .DbgCriticalSections(lang::Switch::On);
 
    for (auto tfInfoIt= Doxyfile.TagFiles.begin() ; tfInfoIt != Doxyfile.TagFiles.end() ; ++tfInfoIt) {
        Lox_Info("Creating index by loading Doxygen tagfile {!Q}. Target URL: {!Q}",
                 tfInfoIt->TagFilePath, tfInfoIt->BaseURL)
 
        // the last one gets is marked as the main file
        bool isLast; {
            auto tfInfoNext= tfInfoIt;
            ++tfInfoNext;
            isLast=  tfInfoNext == Doxyfile.TagFiles.end();
        }
        Index *index;
        {ALIB_LOCK_WITH(DLLock)
           index = MA().New<Index>( tfInfoIt->TagFilePath,
                                    tfInfoIt->BaseURL,
                                    isLast  );       }
        Indices.push_back(index);
        if ( !isLast )
            TPool.ScheduleVoid<IndexLoader>(*index);
        else
            index->Load();
    }
 
    // wait for source readers to be idle (the index loader(s) might still be active)
    scheduleSrcScanners();
    TPool.WaitForAllIdle(10min ALIB_DBG(, 5s));
    Stats.TimeIndexAndSourceLoading= app.stopWatch.Sample();
    
 
    // now launch the HTMLReplacer jobs
    schduleHTMLReplacers();
    TPool.WaitForAllIdle(10min ALIB_DBG(, 5s));
    Stats.TimeHTMLReplacements= app.stopWatch.Sample();
 
 
    #if ALIB_DEBUG
        // in debug-builds we can now switch off critical section checks
        for (auto* index: Indices)
            index->DbgCriticalSectionCheck(alib::lang::Switch::Off);
 
        // in debug-builds and if running on the DXL doc itself, unit tests are performed
        DbgUnitTests(this);
    #endif
 
    // write stats
    writeStatistics();
    app.onSdOutput();
 
    // write error output
    writeErrors();
    app.onSdOutput();
 
    // write links in source not in HTML (This happens when Doxygen was not run)
    writeXLinksInSourceNotInHTML();
    app.onSdOutput();
 
    // write links in HTML not in source (This should never happen. Indicates that the parsers
    // work differently)
    writeXLinksInHTMLNotInSource();
    app.onSdOutput();
 
    // todo:  Option to list all non-used exclamations
 
    // process --doxyfy option
    {
        Variable restoreSources= variables::CampVariable(alib::APPCLI_CAMP, A_CHAR("DOXYFY"), A_CHAR("S") );
        (void) restoreSources.Define();
        if ( restoreSources.GetString().IsNotEmpty() ) {
            Lox_Info("Restoring sources in copy folder {!Q}", restoreSources.GetString())
            scanReplSrcFiles(restoreSources.GetString());
 
            // delete source-locations on XLinks
            for(auto xlinkIt : XLinkMap)
                xlinkIt.second->SourceLocations.clear();
            
            #if ALIB_DEBUG
                // in debug-builds we have to re-enable critical section checks
                for (auto* index: Indices)
                    index->DbgCriticalSectionCheck(alib::lang::Switch::On);
            #endif
            schduleSourceReplacers(restoreSources.GetString());
            TPool.WaitForAllIdle(10min ALIB_DBG(, 5s));
            Stats.TimeSourceReplacements= app.stopWatch.Sample();
 
            #if ALIB_DEBUG
                // in debug-builds we can now switch off critical section checks
                for (auto* index: Indices)
                    index->DbgCriticalSectionCheck(alib::lang::Switch::Off);
            #endif
            writeErrors();
            app.onSdOutput();
        }
 
    }
    // process list option
    #if !defined ENABLE_LIST_OPTION
    {
        Variable listExpression= variables::CampVariable(alib::APPCLI_CAMP, A_CHAR("LIST"), A_CHAR("S") );
        (void) listExpression.Define();
        Variable listFormat= variables::CampVariable(alib::APPCLI_CAMP, A_CHAR("FORMAT"), A_CHAR("S") );
        if (listFormat.Define()) {
            listFormat.GetString().Reset("#{LinkString@!Q} -> \\ref {path} {Display@!Q}");
        }
        if ( listExpression.GetString().IsNotEmpty() ) {
            Lox_Error("listing links({!Q<>}, {!Q'})", listExpression.GetString(), listFormat.GetString())
            listLinks(listExpression.GetString(), listFormat.GetString());
            app.onSdOutput();
        }
    }
    #endif
 
 
    // ----------------------------------------   finalize -------------------------------
    {ALIB_LOCK_WITH(GetSourceTreeLock()) fTreeSources->DeleteAllCustomData<XLinkList>();}
}
 
//--------------------------------------------------------------------------------------------------
//-------------------------------   RegisterLink/GetLink   -----------------------------------------
//--------------------------------------------------------------------------------------------------
XLink *DoxygenXLinks::RegisterXLink(String &searchString) {
    //searchString= "^;DXLApp::bsConfigureCLI;2"; // todo remove
 
    ALIB_LOCK_WITH(DLLock)
    // Get XLink from hash-map
    auto it = XLinkMap.Find(searchString);
    if (it != XLinkMap.end())
        return it->second;
 
    Lox_Verbose("New Xlink registered with #\"{}\"", searchString)
    Stats.UniqueXLinks.fetch_add(1);
    XLink * xLink = MA().New<XLink>();
    xLink->LinkString= String(MA, searchString);
    XLinkMap.EmplaceUnique(xLink->LinkString, xLink);
    return xLink;
}
 
XLink *DoxygenXLinks::GetXLink(String &searchString, const File &htmlFile) {
//searchString= "xyz .HasWarnings"; // todo remove
//if (searchString == ">")
//    int todo= 5;
 
    //--------------- search the XLink in the hash-map ---------------
    XLink *xLink     = nullptr;
    {ALIB_LOCK_WITH(DLLock)
        // Get XLink from hash-map
        auto it = XLinkMap.Find(searchString);
        if (it != XLinkMap.end())
            xLink= it->second;
        else {
            Lox_Info("XLink requested that was not registered, yet:  #\"{}\"", searchString)
            Stats.UniqueXLinks.fetch_add(1);
            xLink = MA().New<XLink>();
            xLink->LinkString= String(MA, searchString);
            XLinkMap.EmplaceUnique(xLink->LinkString, xLink);
        }
    }
 
    //--------------- evaluate the link (if not done, yet) ---------------
    {ALIB_LOCK_WITH(xLink->Lock)
        if ( xLink->IsParsed() ) {
            // if not a local XL, then we're done
            if ( !xLink->IsLocal || xLink->HasErrors())
                return xLink;
 
            // if the given file is invalid, then this is a call from the source-replacer
            // (--doxyfy command). We have a problem now: Only if this link resides in only one
            // html file (and thus was resolved locally only once, we can be sure to give the
            // right answer. If it was used multiple times, we return the first, but we mark
            // this link as erroneous now!
            if( !htmlFile.AsCursor().IsValid() ) {
                int cntLocalCopies= xLink->CountLocalCopies();
                if( cntLocalCopies == 0 )  xLink->Error= XLink::Errors::RestoringUnusedLocalLink;
                if( cntLocalCopies >  1 )  xLink->Error= XLink::Errors::RestoringAmbiguousLocalLink;
                return xLink;
            }
 
            // get a localized version
            auto linkAndIsNew= xLink->GetLocalCopy(htmlFile);
            if (!linkAndIsNew.second)
                return linkAndIsNew.first;
            xLink= linkAndIsNew.first;
            xLink->LocalLinkEntity= Indices.back()->GetHTMLFileEntity(htmlFile);
        } else {
            xLink->Parse();
            if (xLink->HasErrors()) {
                Stats.XLinksWithErrors.fetch_add(1);
                Lox_Info("Error {} parsing the XLink {!Q}: {}", xLink->Error, searchString)
                return xLink;
            }
 
            // local link?
            if ( xLink->IsLocal ) {
                // if the given file is invalid, then this is a call from the source-replacer
                // (--doxyfy command). We have an ever bigger problem now than some lines above:
                // The link was never found in HTML files. So something really went wrong.
                // This will be displayed and explained to the user in the later output
                if( !htmlFile.AsCursor().IsValid() ) {
                    xLink->Error= XLink::Errors::RestoringUnusedLocalLink;
                    return xLink;
                }
 
                auto linkAndIsNew= xLink->GetLocalCopy(htmlFile);
                ALIB_ASSERT(linkAndIsNew.second, "DXL")
                xLink= linkAndIsNew.first;
                if (xLink->HasErrors()) {
                    Stats.XLinksWithErrors.fetch_add(1);
                    Lox_Info("Error {} parsing the XLink {!Q}: {}", xLink->Error, searchString)
                    return xLink;
                }
                xLink->LocalLinkEntity= Indices.back()->GetHTMLFileEntity(htmlFile);
            }
        }
 
        // todo: Parsing has to be checked that no buffer overruns happen. and errors have to be
        //       set and checked above.
        //       Nevertheless, these assertions have to be kept, but changed to error messages
        ALIB_ASSERT(xLink->Name().Length() > 0, "DXL")
 
        // collect results from indices. For local links just check the actual tag file.
        if (!xLink->IsLocal)
            for (auto* index: Indices)
                index->Search(*xLink);
        else
            Indices.back()->Search(*xLink);
 
        //------------- No results: check for files found in HTML file tree -------------
        if ( xLink->Targets.size() == 0 && xLink->KindSpec == Target::File )
            tryResolveHTMLTargetFile(*xLink);
 
        //------------- apply further disambiguation rules -------------
        if ( xLink->Targets.size() > 1 ) {
 
            // rule: If typedef resolver '^' is given and this is not an indirection warning prefix
            //       instead, then type definitions are preferred
            if ( xLink->NoIndirectionWarning)
            {
                bool hasIndirectMemberTargets= false;
                bool hasTypedefTargets       = false;
                for ( auto& result : xLink->Targets ) {
                    hasIndirectMemberTargets |=   result.IsIndirectByInheritance
                                                | result.IsIndirectByTypeDef;
                    hasTypedefTargets        |=   result.Node.IsA(Target::Typedef);
                }
                if (hasTypedefTargets && !hasIndirectMemberTargets)
                    std::erase_if(xLink->Targets, [&](const auto& result) {
                        return !result.Node.IsA(Target::Typedef);
                    });
            }
 
            // rule: remove indirect results if directs exists
            {
                bool hasDirectMemberTargets  = false;
                bool hasIndirectMemberTargets= false;
                for ( auto& result : xLink->Targets )
                    if ( result.IsIndirectByInheritance | result.IsIndirectByTypeDef )
                        hasIndirectMemberTargets= true;
                    else
                        hasDirectMemberTargets= true;
 
                if ( hasDirectMemberTargets && hasIndirectMemberTargets )
                    std::erase_if(xLink->Targets, [&](const auto& result) {
                        return result.IsIndirectByInheritance | result.IsIndirectByTypeDef;
                    });
            }
 
            // rule: remove template specializations if non-specialized exists
            if ( !xLink->SpecializationArgs)
            {
                bool hasNonSpecialized  = false;
                bool hasSpecializations = false;
                for ( auto& result : xLink->Targets )
                    if (auto* rec= result.Cast<TGTRecord>(); rec) {
                        if (rec->SpecializationArgs)
                            hasSpecializations= true;
                        else
                            hasNonSpecialized= true;
                    }
 
                if ( hasNonSpecialized && hasSpecializations )
                    std::erase_if(xLink->Targets, [&](const auto& result) {
                        auto* rec= result.template Cast<TGTRecord>();
                        return  rec && rec->SpecializationArgs;
                    });
            }
 
            // rule: remove const-version of functions (with the same parent)
            if ( xLink->Qualifiers.IsEmpty())
                for ( auto& result : xLink->Targets )
                    if ( auto* t= result.Cast<TGTFunction>();
                        t && t->Qualifiers.IndexOf("const") < 0)
                        std::erase_if(xLink->Targets, [&](const auto& toDelete) {
                            auto* f= toDelete.template Cast<TGTFunction>();
                            return  f && f->Qualifiers.IndexOf("const") >= 0;
                        });
        }
 
        // exactly one match: check if we need to resolve a type definition
        if (    xLink->IsResolved()
             && xLink->NoIndirectionWarning
             && xLink->Result().Node.IsA(Target::Typedef)) {
            xLink->NoIndirectionWarning = false;
            xLink->IsUnderlyingTypeDef  = true;
            xLink->Result().Node= XLink::ResolveTypeDef(xLink->Result().Node, searchString);
            if ( xLink->Result().Node.IsRoot() || !xLink->Result().Node.IsA(Target::RECORD)) {
                xLink->Error= XLink::Errors::TooManyScopeHints;
                xLink->Targets.clear();
            } else {
                xLink->Result().HTMLFile   = xLink->Result().Node.HTMLFile();
                xLink->Result().HTMLAnchor = nullptr;
                xLink->Result().IsResolvedTypeDef= true;
            }
        }
 
        // (still) exactly one match (success!).
        if (xLink->IsResolved()) {
            xLink->AssembleDisplay();
        }
        
        // XLink isn't resolved. Collect error output for later display sorted by link or by file
        else if (xLink->Targets.empty()) {
            Stats.UnresolvedXLinks.fetch_add(1);
            Lox_Info("Search for {!Q} gave no result", searchString)
        }
 
        // Ambiguous XLink.
        else {
            // Collect error output for later display sorted by link or by file
            Stats.AmbiguousXLinks.fetch_add(1);
            Lox_Info("Search for {!Q} gave {} results", searchString, xLink->Targets.size())
        }
 
bool WARNINGS_IGNORE_INDIRECTS= false; // todo: make variable
 
        if ( xLink->IsResolved() && !xLink->IsGood(WARNINGS_IGNORE_INDIRECTS)) {
            Stats.XLinksWithWarnings.fetch_add(1);
            Lox_Info("XLink {!Q} has warnings", searchString)
        }
 
        return xLink;
    }
}
 
//=================================  GetELDecoration  ============================
void DoxygenXLinks::GetELDecoration( Styles& styles,
                                     bool    isELREFAnchor,
                                     File&   elLocation,
                                     String  targetFilename,
                                     String  targetAnchor,
                                     int lineNo, int colNo ) {
 
    if ( verbosityGetELDecoration == Verbosity(-1))
        Lox_GetVerbosity(verbosityGetELDecoration, "ELDECO")
 
    //---------------------- Special cases ----------------------
 
    // check if it links to a "_source"-file
    {
        Substring fName= targetFilename.IsEmpty() ? elLocation.Name() : targetFilename;
        integer pos= fName.LastIndexOf('.');
        if (pos >= 0) {
            String stem= fName.Substring(0, pos);
            if (stem.EndsWith("_source") ) {
                styles.Add(Styles::SrcFile);
                if (targetAnchor.IsNotEmpty()){
                    ALIB_ASSERT(targetAnchor.StartsWith("l0"), "DXL/ELDECO")
                    styles.Add(Styles::SrcFileLine);
                }
                styles.Add(Styles::FileOrDir);
                styles.isFile= true;
                return;
            }
        }
    }
 
    // check if it links to a "dir_"-file
    if (targetFilename.StartsWith("dir_") ) {
        ALIB_ASSERT(targetAnchor.IsEmpty(), "DXL/ELDECO")
        styles.Add(Styles::Dir);
        styles.Add(Styles::FileOrDir);
        styles.isDir= true;
        return;
    }
 
    //---------------------- standard cases ----------------------
    Index::Node node;
 
    // if no file name is given, this is a local anchor in the HTML file.
    // Thus it has to be in the main index
    if (targetFilename.IsEmpty()) {
        // search in file-map
        if (targetAnchor.IsEmpty()) {
            ALIB_LOCK_SHARED_WITH(Indices.back()->SLock)
            auto it= Indices.back()->fileMap.Find(elLocation.Name());
            if ( it == Indices.back()->fileMap.end() ) {
                if (!isELREFAnchor) Stats.ELReplacementsUnresolved   .fetch_add(1);
                else                Stats.ELREFReplacementsUnresolved.fetch_add(1);
                Lox_Warning("ELDECO", "File {!Q} not found in main index.", elLocation.Name())
                styles.Add(Styles::ELUnknown);
                return;
            }
 
            if ( verbosityGetELDecoration >= Verbosity::Info)
                Lox_Info("ELDECO", "Found file {!Q} in main index.", elLocation.Name())
            node= Indices.back()->ImportCursor(it->second);
 
        // search in anchor-map
        } else {
            ALIB_LOCK_SHARED_WITH(Indices.back()->SLock)
            auto it= Indices.back()->anchorMap.Find({elLocation.Name(), targetAnchor});
            if ( it == Indices.back()->anchorMap.end() ) {
                if ( verbosityGetELDecoration > Verbosity::Warning)
                    Lox_Warning("ELDECO", "EL-Anchor of HTML file main index. Target: {}/{}#{} "
                                          "HTML-Location: {0}/{}:{}:{}",
                                          Indices.back()->BaseURL, elLocation.Name(), targetAnchor,
                                          elLocation.Name(), lineNo, colNo )
                if (!isELREFAnchor) Stats.ELReplacementsUnresolved   .fetch_add(1);
                else                Stats.ELREFReplacementsUnresolved.fetch_add(1);
                styles.Add(Styles::ELUnknown);
                return;
            }
            node= Indices.back()->ImportCursor(it->second);
        }
 
    // a file name is given: can be any of the indices (also the main index, if not an ELREF anchor)
    } else {
        // remove the base URL from the file name
        size_t indexIdx= size_t(-1);
        for (size_t idx= 0 ; idx < Indices.size() - (isELREFAnchor? 1 : 0) ; ++idx) {
            auto* index= Indices[idx];
            if ( targetFilename.StartsWith(index->BaseURL) ) {
                indexIdx= idx;
                targetFilename= targetFilename.Substring(index->BaseURL.Length());
                     if (targetFilename.StartsWith("/") || targetFilename.StartsWith("\\"))
                         targetFilename= targetFilename.Substring(1);
                break;
            }
        }
 
        // search in file-map
        if ( targetAnchor.IsEmpty() ) {
            bool found= false;
            for (size_t idx= 0 ; idx < Indices.size() - (isELREFAnchor? 1 : 0) ; ++idx) {
                if (indexIdx != size_t(-1) && idx != indexIdx)
                    continue;
                auto* index= Indices[idx];
                ALIB_LOCK_SHARED_WITH(index->SLock)
                auto it= index->fileMap.Find(targetFilename);
                if ( it != index->fileMap.end() ) {
                    node= index->ImportCursor(it->second);
                    found= true;
                    break;
                }
            }
            if (!found) {
                Lox_Warning("ELDECO", "File {!Q} not found in any index.", targetFilename)
                if (!isELREFAnchor) Stats.ELReplacementsUnresolved   .fetch_add(1);
                else                Stats.ELREFReplacementsUnresolved.fetch_add(1);
                styles.Add(Styles::ELUnknown);
                return;
            }
            if ( verbosityGetELDecoration >= Verbosity::Info)
                Lox_Info("ELDECO", "Found file {!Q} in index {}:{}.", targetFilename,
                                      node.Index().FilePath, node.LineNo())
 
        // search in anchor-map
        } else {
            bool found= false;
            for (size_t idx= 0 ; idx < Indices.size() ; ++idx) {
                if (indexIdx != size_t(-1) && idx != indexIdx)
                    continue;
                auto* index= Indices[idx];
                ALIB_LOCK_SHARED_WITH(index->SLock)
                auto it= index->anchorMap.Find({targetFilename, targetAnchor});
                if ( it != index->anchorMap.end() ) {
                    node= index->ImportCursor(it->second);
                    found= true;
                    break;
                }
            }
            if (!found) {
                if ( verbosityGetELDecoration >= Verbosity::Warning)
                    Lox_Warning("ELDECO",
                        "EL-Anchor of HTML file not found in any index. Target: {} # {} "
                        "HTML-Location: {}/{}:{}:{}",
                        targetFilename, targetAnchor,
                        Indices.back()->BaseURL, elLocation.Name(), lineNo, colNo )
                if (!isELREFAnchor) Stats.ELReplacementsUnresolved   .fetch_add(1);
                else                Stats.ELREFReplacementsUnresolved.fetch_add(1);
                styles.Add(Styles::ELUnknown);
                return;
            }
 
            if ( verbosityGetELDecoration >= Verbosity::Info)
                Lox_Info("ELDECO", "Found file/anchor {}/{}#{} in index. HTML-Location {0}/{}:{}.",
                                    node.Index().BaseURL, targetFilename, targetAnchor,
                                    elLocation.Name(), lineNo, colNo)
        }
    }
 
    ALIB_ASSERT(node.IsValid(), "DXL/ELDECO")
    styles.Set( node, false, false );
    styles.Add(Styles::XLEL);
}
 
//=================================  writeErrors  ============================
void DoxygenXLinks::writeErrors() {
    Lox_SetDomain("RESULT", Scope::Method)
    Lox_Info("Writing non-resolved or ambiguous XLinks. (The main output)")
 
    DXLApp &app = app::Get<DXLApp>();
 
    // reset all xlink in respect to print information.
    for(auto xLinkIt : XLinkMap )
        xLinkIt.second->WasPrinted= false;
 
    // ReSharper disable CppDFAUnreachableCode
    ALIB_LOCK_SHARED_WITH(GetSourceTreeLock())
    StringTreeIterator<FTree> treeIt;
    RecentlyModifiedFirst     sorter;
    treeIt.SetPathGeneration(lang::Switch::On);
    treeIt.SetSorting(&sorter);
    treeIt.Initialize(fTreeSources->Root().AsCursor(), lang::Inclusion::Exclude);
 
    int cntLocations   = 0;
 
    // main loop over all source files
    while (treeIt.IsValid()) {
        File actFile(treeIt.Node());
 
        // no links attached to that source file?
        if (!actFile.HasCustomData()) {
            Lox_Verbose("No unresolved XLinks found with file {}:1", treeIt.Path())
            treeIt.Next();
            continue;
        }
 
        auto &linksInSrc = actFile.GetCustomData<XLinkList>();
        Lox_Info("Found {} (unique) XLinks with file {}:1",
                 linksInSrc.size(), treeIt.Path())
 
        bool SUPPRESS_WARNINGS= false; // todo: make variable
 
        // loop over all links in the source file
        for (auto &linkInSrc: linksInSrc) {
            if ( !linkInSrc.XL->IsParsed() ) {
                Lox_Info("Found {} XLink #{!Q} in sources which was not evaluated yet, "
                         "hence not found in HTML files." , linkInSrc.XL->LinkString)
                linkInSrc.XL->NotFoundInHTML= true;
                continue;
            }
            if (linkInSrc.XL->NotFoundInHTML)
                continue;
 
            // loop over a) just the XLink, or b) all local versions of it
            XLink* xlOrCopy= linkInSrc.XL;
            while (xlOrCopy) {
                // check if written
                if (xlOrCopy->WasPrinted) {
                    break;
                }
                xlOrCopy->WasPrinted = true;
 
                if (  xlOrCopy->IsGood( SUPPRESS_WARNINGS  ) ) {
                   while ((xlOrCopy= xlOrCopy->NextLocal) != nullptr )
                        if ( !xlOrCopy->IsResolved() )
                            break;
                   continue;
                }
 
                Lox_Info("{} XLink {!ATab!Q} @ {}:{}:{}",
                           xlOrCopy->Targets.size() >  1 ? "Ambiguous"
                         : xlOrCopy->Targets.size() == 0 ? "Unresolved"
                         : xlOrCopy->HasErrors()         ? "Error in"
                         :                                 "Warning in",
                         xlOrCopy->LinkString, treeIt.Path(), linkInSrc.Line, linkInSrc.Column)
 
                String256 path(treeIt.Path());
                {ALIB_LOCK_RECURSIVE_WITH(Formatter::DEFAULT_LOCK)
                xlOrCopy->PrintError(*app.cErr, xlOrCopy->LinkString); }
                cntLocations+= xlOrCopy->SourceLocations.size();
                app.cErr->PushIndent(2);
 
                // loop over all occurrences of this XLink in sources.
                // We do our sorting of source files once more, only then it is rightfully sorted
                StringTreeIterator<FTree> innerTrIt;
                innerTrIt.SetPathGeneration(lang::Switch::On);
                innerTrIt.SetSorting(&sorter);
                innerTrIt.Initialize(fTreeSources->Root().AsCursor(), lang::Inclusion::Exclude);
 
                // inner loop over all source files
                while (innerTrIt.IsValid()) {
                    system::Path locationPath;
                    for (auto &srcLoc: linkInSrc.XL->SourceLocations)
                        if (innerTrIt.Node() == srcLoc.File.AsCursor()) {
                            if (locationPath.IsEmpty())
                                File(innerTrIt.Node()).AssembleSymbolicPath(locationPath, lang::Inclusion::Include);
                            Lox_Info("       @ {}:{}:{}", locationPath, srcLoc.Line, srcLoc.Column)
                            app.cErr->Add( "@ {}:{}:{}", locationPath, srcLoc.Line, srcLoc.Column);
                        }
                    innerTrIt.Next();
                
                }
 
                // This is a copy of the local link
                if ( xlOrCopy->IsLocal && xlOrCopy->HTMLFileOfLocalLink.IsValid() ) {
                    app.cErr->Add( "This local XLink's HTML file: {}", // Todo Hier muss dann das target scope hinkommen, wenn das gemacht ist
                                    GetHTMLTree().ImportCursor(xlOrCopy->HTMLFileOfLocalLink).Name()  );
                }
 
                app.cErr->Add(NEW_LINE);
                app.cErr->PopIndent();
 
                while ((xlOrCopy= xlOrCopy->NextLocal) != nullptr )
                    if ( !xlOrCopy->IsResolved() )
                        break;
            } // loop over all xLinks
        }
 
        // next file
        treeIt.Next();
    } // loop over all source files
 
 
    // ReSharper restore CppDFAUnreachableCode
    auto cntErrs=     Stats.UnresolvedXLinks.load()
                    + Stats.AmbiguousXLinks.load()
                    + Stats.XLinksWithErrors;
    if ( cntErrs > 0) {
        app.cErr->Add("Error summary: {} erroneous XLinks @ {} locations.", cntErrs, cntLocations
        );
    }
 
    if ( Stats.XLinksWithWarnings.load() > 0) {
        app.cErr->Add("Warning summary: {} XLinks with warnings."
                       , Stats.XLinksWithWarnings.load() + Stats.AmbiguousXLinks.load()
        );
    }
}
 
//=================================  listLinks ============================
void DoxygenXLinks::listLinks(const String& expressionString, const String& format ) {
    if ( expressionString.IsEmpty())
        return;
 
    Lox_SetDomain("LIST", Scope::Method)
    DXLApp &app = app::Get<DXLApp>();
    app.stopWatch.Sample();
 
 
    //----------------- compile expression -----------------
    try {
        DXLExpression expr(expressionString);
        if(! (    expr.ResultType().IsType<bool>()
               || expr.ResultType().IsType<integer>() ) ) {
            app.cErr->Add("{}-Expressions need to evaluate to boolean or integer values.\n"
                          "  Given expression string:      {!Q}\n"
                          "  Normalized expression string: {!Q}\n"
                          "  Result type:                  {}"
                          , app.GetName(), expressionString, expr.GetExpressionString()
                          ,  expr.ResultType().IsType<long>()    ? "long"
                            :expr.ResultType().IsType<String>() ? "String"
                            :                                     "Unknown"
                            );
            return;
        }
 
        Lox_Info( "Expression sucessfully compiled:\n"
                  "  Given expression string:      {!Q}\n"
                  "  Normalized expression string: {!Q}\n"
                  "  Result type:                  {}"
                  , expressionString, expr.GetExpressionString()
                  ,  expr.ResultType().IsType<long>()   ? "integral"
                    :expr.ResultType().IsType<String>() ? "String"
                    :                                     "Unknown"  )
 
        if (expr.IsConstant())
            app.cOut->Add("Attention: The given expression is constant:\n"
                          "  Given expression string:      {!Q}\n"
                          "  Normalized expression string: {!Q}\n"
                          "  Optimized expression string:  {!Q}"
                          , app.GetName(), expressionString
                          , expr.GetOptimizedString() );
 
        // Reset printing flag
        for (auto& xLink : XLinkMap)
            xLink.second->WasPrinted = false;
 
        // ReSharper disable CppDFAUnreachableCode
        ALIB_LOCK_SHARED_WITH(GetSourceTreeLock())
        StringTreeIterator<FTree> treeIt;
        RecentlyModifiedFirst           sorter;
        treeIt.SetPathGeneration(lang::Switch::On);
        treeIt.SetSorting(&sorter);
        treeIt.Initialize(fTreeSources->Root().AsCursor(), lang::Inclusion::Exclude);
 
        int cntXLinks      = 0;
        int cntLocations   = 0;
 
        // create the expression formatter
        DXLExpressionFormatter exprFormatter( format );
        DXLScope dxlScope;
 
        // main loop over all source files
        while (treeIt.IsValid()) {
            File actFile(treeIt.Node());
 
            // no links attached to that source file?
            if (!actFile.HasCustomData()) {
                treeIt.Next();
                continue;
            }
            auto &linksInSrc = actFile.GetCustomData<XLinkList>();
 
            // loop over all links in the source file
            for (auto &linkInSrc: linksInSrc) {
                // check if written
                if (linkInSrc.XL->WasPrinted)
                    continue;
                linkInSrc.XL->WasPrinted = true;
 
                // evaluate expression
                if ( !expr.Includes(linkInSrc.XL)  )
                    continue;
 
                ++cntXLinks;
 
                String256 path(treeIt.Path());
                app.cOut->Add(NEW_LINE);
 
                dxlScope.Xlink     = linkInSrc.XL;
 
                {ALIB_LOCK_RECURSIVE_WITH(Formatter::DEFAULT_LOCK)
                exprFormatter.Format( app.cOut->Buffer,  dxlScope ); }
 
                app.cOut->PushIndent(2);
                app.cOut->Add("@ {}:{}:{}",
                              path, linkInSrc.Line, linkInSrc.Column);
 
                // loop over all occurrences of this XLink in other sources
                for (auto &srcInLink: linkInSrc.XL->SourceLocations) {
                    ++cntLocations;
                    // skip if this the current position
                    if (   srcInLink.File.AsCursor() == treeIt.Node()
                        && srcInLink.Line            == linkInSrc.Line
                        && srcInLink.Column          == linkInSrc.Column)
                        continue;
                    system::Path furtherPath;
                    srcInLink.File.AssembleSymbolicPath(furtherPath, lang::Inclusion::Include);
                    app.cOut->Add( "@ {}:{}:{}", furtherPath, srcInLink.Line, srcInLink.Column);
                }
                app.cOut->PopIndent();
            }
 
            // next file
            treeIt.Next();
        } // loop over all source files
 
 
        // ReSharper restore CppDFAUnreachableCode
        app.cOut->Add("List summery: Found {} XLinks @ {} locations that match expression {}.\n"
                      "Query generation time: {}"
 
                       , cntXLinks
                       , cntLocations
                       , expr.GetExpressionString()
                       , app.stopWatch.Sample()
        );
 
    //--------------------- exception handling ----------------
    } catch (Exception& e) {
        Lox_Exception(e, Verbosity::Error )
        app.cErr->Add("Error parsing expression {!Q}:", expressionString);
        String512 exceptionMsg;
        {ALIB_LOCK_RECURSIVE_WITH(Formatter::DEFAULT_LOCK)
        e.Format(exceptionMsg); }
 
        app.cErr->Add(exceptionMsg);
    }
}
 
//=================================  writeXLinksInSourceNotInHTML ============================
void DoxygenXLinks::writeXLinksInSourceNotInHTML() {
    Lox_SetDomain("RESULT", Scope::Method)
    // count all links with unresolved HTML file
    int cntSrcOnlyLinks= 0;
    for (auto& it : XLinkMap)
        if (    it.second->HTMLLocations.empty()
             || (it.second->IsLocal && !it.second->HTMLFileOfLocalLink.IsValid()) )
            ++cntSrcOnlyLinks;
 
    if ( cntSrcOnlyLinks == 0)
        return;
 
    DXLApp &app = app::Get<DXLApp>();
    app.cErr->Add("Found {} unique XLinks in sources, which are not in HTML files.\n"
                  "  Note: This usually happens if the DoxygenXLinks was run twice. In other\n"
                  "        words, when doxygen was not run before running the DoxygenXLinks.\n"
                  "        Another option is that XLinks appeared in code that was not\n"
                  "        used by doxygen to write output. For example, due to preprocessor \n"
                  "        switches or because the XLink was (accidentially) located in a standard\n"
                  "        comment.\n"
                  "\n"
                  "  Printing the first 5:\n",
                   cntSrcOnlyLinks );
    int cnt= 5;
    app.cErr->PushIndent(2);
    for (auto& it : XLinkMap ) {
        if (     !it.second->HTMLLocations.empty()
             &&  !(it.second->IsLocal && !it.second->HTMLFileOfLocalLink.IsValid()) )
            continue;
        if (--cnt < 0)
            break;
        app.cErr->Add( "XLink #{!Q}", it.first );
        app.cErr->PushIndent(2);
        for ( auto& loc : it.second->SourceLocations ) {
            system::Path path;
            { ALIB_LOCK_SHARED_WITH(GetSourceTreeLock())
                loc.File.AssembleSymbolicPath(path, lang::Inclusion::Include);     }
            app.cErr->Add( "@ {}:{}:{}", path, loc.Line, loc.Column  );
        }
        app.cErr->PopIndent();
    }
    app.cErr->PopIndent();
}
 
void DoxygenXLinks::writeXLinksInHTMLNotInSource() {
    Lox_SetDomain("RESULT", Scope::Method)
    // count all links with unresolved HTML file
    int cntHTMLOnlyLinks= 0;
    for (auto& it : XLinkMap)
        if ( it.second->SourceLocations.empty() )
            ++cntHTMLOnlyLinks;
 
    if ( cntHTMLOnlyLinks == 0)
        return;
 
    DXLApp &app = app::Get<DXLApp>();
    app.cErr->Add("Found {} unique XLinks in HTML files, which were not found in the sources.\n"
                  "  Note: This should not happen. It might indicate that {} does not read\n"
                  "        the sources rightfully. Maybe it misinterprets the doxygen INI-file.\n"
                  "        It is not allowed to create XLinks using Doxygen macros. Use the \\\\ref syntax there!\n"
                  "        In case you cannot find the reason, please report it as a bug.\n"
                  "        (If so, please include a short sample. Thank you!)\n"
                  "\n"
                  "Printing the first 5:\n"
                  ,cntHTMLOnlyLinks, app.GetName()  );
    int cnt= 5;
 
    app.cErr->PushIndent(2);
    for (auto& it : XLinkMap ) {
        if ( !it.second->SourceLocations.empty() )
            continue;
        if (--cnt < 0)
            break;
        app.cErr->Add( "XLink #{!Q}" ,it.first );
        app.cErr->PushIndent(2);
        for ( auto& loc : it.second->HTMLLocations ) {
            system::Path path;
            { ALIB_LOCK_SHARED_WITH(GetHTMLTreeLock())
                loc.File.AssembleSymbolicPath(path, lang::Inclusion::Include);           }
            app.cErr->Add( "@ {}:{}:{}", path ,loc.Line ,loc.Column );
        }
        app.cErr->PopIndent();
    }
    app.cErr->PopIndent();
}
//=================================  writeStatistics ============================
void DoxygenXLinks::writeStatistics() {
    Lox_SetDomain("RESULT", Scope::Method)
    DXLApp &app = app::Get<DXLApp>();
 
    // statistics count XLink locations
    int srcLocationsGood         = 0;
    int htmlLocationsGood        = 0;
    int srcLocationsWithErrors   = 0;
    int htmlLocationsWithErrors  = 0;
    int srcLocationsUnresolved   = 0;
    int htmlLocationsUnresolved  = 0;
    int srcLocationsAmbiguous    = 0;
    int htmlLocationsAmbiguous   = 0;
    int srcLocationsWithWarnings = 0;
    int htmlLocationsWithWarnings= 0;
 
    for (auto &it: XLinkMap) {
        XLink& xLink= *it.second;
        Lox_Info("Dump", "XLink found: {} {!ATab}", it.first, it.second->IsResolved())
             if( xLink.IsGood(false))                   { srcLocationsGood         += xLink.SourceLocations.size();
                                                          htmlLocationsGood        += xLink.HTMLLocations  .size(); }
        else if( xLink.HasErrors())                     { srcLocationsWithErrors   += xLink.SourceLocations.size();
                                                          htmlLocationsWithErrors  += xLink.HTMLLocations  .size(); }
        else if( xLink.Targets.size() ==0 )             { srcLocationsUnresolved   += xLink.SourceLocations.size();
                                                          htmlLocationsUnresolved  += xLink.HTMLLocations  .size(); }
        else if( xLink.Targets.size() > 1 )             { srcLocationsAmbiguous    += xLink.SourceLocations.size();
                                                          htmlLocationsAmbiguous   += xLink.HTMLLocations  .size(); }
        else                                            { srcLocationsWithWarnings += xLink.SourceLocations.size();
                                                          htmlLocationsWithWarnings+= xLink.HTMLLocations  .size(); }
    }
 
    Variable getStatistics= variables::CampVariable(alib::APPCLI_CAMP, A_CHAR("STATISTICS"), A_CHAR("B") );
    if( getStatistics.Define() )
        getStatistics= false;
 
    // short version if option "--STATISTICS" is not set
    app.stopWatch.Sample();
 
    if (!getStatistics.GetBool()) {
        app.cOut->Add( "{} finished: {!ATab:,} XLinks replaced in {:,} html files. "
                       "Identified {:,} locations in {:,} source files.\n"
                       "Execution time: {}"
                      , app.GetName()
                      , htmlLocationsGood
                      , Stats.HTMLFiles.load()
 
                      , srcLocationsGood
                      , Stats.SourceFiles.load()
                      
                      , app.stopWatch.GetCumulated()
        );
        return;
    }
 
    //----------------------------------- long version -----------------------------------
    {
        String512 parameters;
        for (int i= 1; i < ARG_C; ++i )
            parameters << ARG_VN[i] << ' ';
        app.cOut->AddMarked( "\nStatistics of command: {} {}\n@HL= ", app.GetName(), parameters );
    }
 
    // tag-files
    app.cOut->Add("Tag-files:\n============");
    app.cOut->PushIndent(2);
    unsigned ctdTagFiles= 0;
    integer  maxTagFileNameLen= 0;
    for (auto &index: Indices) {
        app.cOut->Add("No {}: {:,6} lines read, file {!Q}, URL: {}, load time {}",
                        ctdTagFiles + 1,
                        index->StatCtdLines, index->FilePath, index->BaseURL, index->LoadTime);
        maxTagFileNameLen= std::max(maxTagFileNameLen, index->FileName.Length());
        ++ctdTagFiles;
    }
    std::vector<int> kindSums;
    kindSums.reserve(ctdTagFiles);
 
    {ALIB_LOCK_RECURSIVE_WITH(Formatter::DEFAULT_LOCK)
        auto& fmt= app.cOut->Formatter;
        auto& buf= app.cOut->Buffer;
        buf << NEW_LINE;
        // headline
        buf <<  "   Type           ";
        for ( unsigned i= 0; i< ctdTagFiles ; ++i)
            fmt->Format(buf,  String64("|{:>")._(maxTagFileNameLen)._("} "), Indices.at(i)->FileName);
        buf << NEW_LINE;
        buf <<  "  ----------------";
        for ( unsigned tf= 0; tf< ctdTagFiles ; ++tf) {
            fmt->Format(buf,  "|-{!FillC-}", maxTagFileNameLen);
            kindSums.push_back(0);
        }
        buf << NEW_LINE;
 
        // Kinds
        for (int kindIdx= 0 ; kindIdx < int(Target::MAX_KIND) ; ++kindIdx) {
            Target::Kinds kind = Target::Kinds(1<<kindIdx);
            if ( kind == Target::FILEPATH_COMPONENT )//|| !index->KindStats.Count[i] )
                continue;
            fmt->Format(buf,  "   {:14} ", kind);
            for ( unsigned tf= 0; tf< ctdTagFiles ; ++tf) {
                fmt->Format(buf,  String64("|{:,")._(maxTagFileNameLen)._("} ")
                                 ,Indices[tf]->KindStats.GetByIdx(kindIdx) );
                kindSums[tf]+= Indices[tf]->KindStats.GetByIdx(kindIdx);
            }
            buf << NEW_LINE;
        }
        // Sums
        buf <<  "  ----------------";
        for ( unsigned tf= 0; tf< ctdTagFiles ; ++tf)
            fmt->Format(buf,  "|-{!FillC-}", maxTagFileNameLen);
        buf << NEW_LINE;
        buf <<  "             Sum  ";
        for ( unsigned i= 0; i< ctdTagFiles ; ++i)
            fmt->Format(buf,  String64("|{:,")._(maxTagFileNameLen)._("} "), kindSums[i]);
        buf << NEW_LINE;
    }
    app.cOut->PopIndent();
 
    //----------------- files and locations -----------------
    app.cOut->Add(NEW_LINE);
    app.cOut->Add("XLinks:\n============");
    app.cOut->PushIndent(2);
    app.cOut->Add("               |  Sources |    HTML  | Unique/Total \n"
                  "---------------|----------|----------|--------------"     );
    app.cOut->Add("XLinks         |{:9,} |{:9,} |{:9,}\n"
                    ,   srcLocationsGood + srcLocationsUnresolved + srcLocationsAmbiguous
                      + srcLocationsWithErrors + srcLocationsWithWarnings
                    ,   htmlLocationsGood + htmlLocationsUnresolved + htmlLocationsAmbiguous
                      + htmlLocationsWithErrors + htmlLocationsWithWarnings
                    , Stats.UniqueXLinks.load()  );
 
    app.cOut->Add("    Unresolved |{:9,} |{:9,} |{:9,}\n" , srcLocationsUnresolved,
                  htmlLocationsUnresolved, Stats.UnresolvedXLinks.load() );
 
    app.cOut->Add("     Ambiguous |{:9,} |{:9,} |{:9,}\n" , srcLocationsAmbiguous,
                  htmlLocationsAmbiguous, Stats.AmbiguousXLinks.load() );
 
    app.cOut->Add("     Erroneous |{:9,} |{:9,} |{:9,}\n", srcLocationsWithErrors,
                  htmlLocationsWithErrors, Stats.XLinksWithErrors.load() );
 
    app.cOut->Add("      Warnings |{:9,} |{:9,} |{:9,}\n", srcLocationsWithWarnings,
                  htmlLocationsWithWarnings, Stats.XLinksWithWarnings.load() );
 
    app.cOut->Add("EL-Anchors     |      -/- |{:9,} |{0:9,}\n", Stats.ELReplacements.load() );
    app.cOut->Add("    Unresolved |      -/- |{:9,} |{0:9,}\n", Stats.ELReplacementsUnresolved.load());
    app.cOut->Add("ELREF-Anchors  |      -/- |{:9,} |{0:9,}\n", Stats.ELREFReplacements.load() );
    app.cOut->Add("    Unresolved |      -/- |{:9,} |{0:9,}\n", Stats.ELREFReplacementsUnresolved.load());
    app.cOut->Add("---------------|----------|----------|--------------\n");
    app.cOut->Add("         Files |{:9,} |{:9,} |{:9,}\n", Stats.SourceFiles.load(),
                  Stats.HTMLFiles.load(), Stats.SourceFiles.load()  + Stats.HTMLFiles.load()  );
    app.cOut->Add("         Lines |{:9,} |{:9,} |{:9,}\n", Stats.SourceFileLines.load()
                    , Stats.HTMLFileLines.load(), Stats.SourceFileLines.load()  + Stats.HTMLFileLines.load() );
    app.cOut->Add("          Size |{:>9} |{:>9} |{:>9}\n"
                    , format::ByteSizeIEC(uinteger( Stats.SourceFileSize.load() ))
                    , format::ByteSizeIEC(uinteger( Stats.HTMLFileSize.load() ))
                    , format::ByteSizeIEC(uinteger( Stats.SourceFileSize.load()  + Stats.HTMLFileSize.load() ))
                    );
    app.cOut->Add("          Time |{:>9} |{:>9} |{:>9}\n", Stats.TimeIndexAndSourceLoading
                    , Stats.TimeHTMLReplacements, Stats.TimeIndexAndSourceLoading + Stats.TimeHTMLReplacements  );
 
    app.cOut->PopIndent();
 
    // Times
    app.cOut->Add(NEW_LINE);
    app.cOut->Add("Total Time: {}", app.stopWatch.GetCumulated());
}
 
void DoxygenXLinks::tryResolveHTMLTargetFile(XLink& xLink) {
    // checks
    ALIB_ASSERT_ERROR(xLink.KindSpec == Target::File, "DXL",
                                    "XLink must be of kind 'File' to be resolved from HTML file")
    ALIB_ASSERT_ERROR(xLink.Targets.size() == 0, "DXL",
                                    "This method must only be called if on unresolved links")
    if ( xLink.Error != XLink::Errors::OK)
        return;
 
    // convert file name
    system::Path dxNameNormal;
    system::Path dxNameSource;
    {
        String name = xLink.Name();
        for( auto c : name ) switch(c)  {
                case '_': dxNameNormal << "__"; break;
                case '-': dxNameNormal << "_0"; break;
                case '.': dxNameNormal << "_8"; break;
                case ':': dxNameNormal << "_1"; break;
                case '/': dxNameNormal << "_2"; break;
                case '<': dxNameNormal << "_3"; break;
                case '>': dxNameNormal << "_4"; break;
                case '*': dxNameNormal << "_5"; break;
                case '&': dxNameNormal << "_6"; break;
                case '|': dxNameNormal << "_7"; break;
                case '!': dxNameNormal << "_9"; break;
                case ',': dxNameNormal << "_a"; break;
                default:  dxNameNormal << c;    break;
        }
    }
    dxNameSource << dxNameNormal << "_source";
    dxNameNormal << Doxyfile.HtmlFileExtension;
    dxNameSource << Doxyfile.HtmlFileExtension;
 
    // ReSharper disable CppDFAUnreachableCode
 
    File foundNormal;
    File foundSource;
    {ALIB_LOCK_SHARED_WITH(GetHTMLTreeLock())
        StringTreeIterator<FTree> treeIt;
        treeIt.Initialize(fTreeHTML->Root().AsCursor(), lang::Inclusion::Exclude);
        while (treeIt.IsValid()) {
            if ( !xLink.NoIndirectionWarning &&  treeIt.Node().Name().Equals(dxNameNormal) )
                foundNormal= treeIt.Node();
            if (  xLink.NoIndirectionWarning &&  treeIt.Node().Name().Equals(dxNameSource) )
                foundSource= treeIt.Node();
            treeIt.Next();
    }    }
 
    // ReSharper restore CppDFAUnreachableCode
    if ( foundNormal.AsCursor().IsInvalid() && foundSource.AsCursor().IsInvalid() )
        return;
 
    if (foundNormal.AsCursor().IsValid() && !xLink.NoIndirectionWarning) foundSource= File();
    if (foundSource.AsCursor().IsValid() &&  xLink.NoIndirectionWarning) foundNormal= File();
    ALIB_ASSERT(!(foundNormal.AsCursor().IsValid() && foundSource.AsCursor().IsValid()), "DXL")
 
    // create a new file-node in the Index!
    Index& index= *Indices.back();
    String256 path;
    for (int i= 0; i < xLink.ScopeSize(); ++i)
        path << xLink.Scope(i) << index.Separator();
    path << xLink.Name();
    if ( foundSource.AsCursor().IsValid() )
        path << "_source";
 
    Index::Node node= index.Root();
    { ALIB_LOCK_WITH(index.SLock)
        static TGTFilePathComponent filePathComponentTag(-1);
        bool created= node.AsCursor().GoToCreatedPathIfNotExistent(path, &filePathComponentTag) != 0;
        if ( created ) {
            auto* tgtFile= index.ma().New<TGTFile>(
                                        (foundNormal.AsCursor().IsValid() ? foundNormal
                                                                          : foundSource).Name()
                                        , 0 );
            node.ReplaceTarget(tgtFile);
        }
    }
 
    xLink.Targets.push_back({ node
                             ,index.BaseURL
                             ,node.HTMLFile()
                             ,EMPTY_STRING
                             ,false,false,false,false, false
                             ,true                               // LinksToAScannedHTMLFile
                             ,foundSource.AsCursor().IsValid()   // IsIndirectLinkToScannedHTMLSourceFile
                           });
 
    
}
} //namespace [dxl]