dxlapp.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 "dxlapp.hpp"
#include "dxl.hpp"
#include "index.hpp"
 
#include "ALib.Lang.H"
#include "ALib.ALox.Impl.H"
#include "ALib.Bootstrap.H"
#include "ALib.Camp.Base.H"
 
 
#include <iostream>
#include <algorithm>
 
using namespace alib;
 
 
namespace dxl {
 
DXLApp::DXLApp()
: AppCli{}  {
    flags +=   Flags::CreateReleaseLox
             + Flags::UseReleaseLoggerForDebugLogging
             + Flags::ALoxVerbosityExportAllAndWriteBackRelLogger;
}
 
void DXLApp::onBsPrepareResources() {
    // call parent's implementation. This bulk-loads the resources into the camps.
    AppCli::onBsPrepareResources();
 
    // now, we just add the resources that parent AppCli did not define for us.
 
    APPCLI_CAMP.GetResourcePool().BootstrapBulk( APPCLI_CAMP.ResourceCategory,
#define EOS ,
 
//-------------------- Things required by AppCli --------------------
"AppName",              "DoxygenXLinks",
"AppInfo",              "@HL-"
                        "{} V.{}.\n"
                        "(c) 2025-{} AWorx GmbH.\n"
                        "    Published under MIT License (Open Source).\n"
                        "More information is found at: https://alib.dev/DoxygenXLinks.\n" // <-todo: what will be the URL?
                        "@HL-",
 
"AppStart",          A_CHAR("{} {} started."),
"DryRunStart",       A_CHAR("!!! Dry-run mode - HTML-files will not be written!!!\n"),
//"DryRunEnd",         A_CHAR(""),
 
"HlpUsage"     ,  A_CHAR("sample [format=\"FORMATSPEC\" [now]|[file FILENAME]"),
"HlpCLIAppName",  A_CHAR("DoxygenXLinks"),
 
//todo Im AppCli kann man noch keine Resourcen überschreiben. Nicht dass ich die hier überschreiben
//     will, aber grundsätzlich muss das notürlich gehen. Hatte ich eh noch vor..
//"AppVersion",           "V.{}.",
//"DryRunStart",          "{} dry-run mode:\n@>>",
//"DryRunEnd",            "@<<",
 
//----------------------------------------- Enums -----------------------------------------
"Kinds",
 "^0,"   "dir"                ",3,"
 "^1,"   "file"               ",4,"
 "^2,"   "page"               ",4,"
 "^3,"   "group"              ",5,"
 "^4,"   "docanchor"          ",4,"
 
 "^5,"   "namespace"          ",5,"
 "^6,"   "struct"             ",5,"
 "^7,"   "class"              ",4,"
 "^8,"   "union"              ",5,"
 "^9,"   "concept"            ",5,"
 
"^10,"   "define"             ",5,"
"^11,"   "typedef"            ",1,"
"^12,"   "variable"           ",1,"
"^13,"   "function"           ",2,"
"^14,"   "enumeration"        ",5,"
"^15,"   "enumvalue"          ",5,"
"^16,"   "generic_member"     ",3,"
 
 
"^17,"   "FILEPATH_COMPONENT" ",5,"
"^18,"   "UNKNOWN"            ",3,"
"^19,"   "UNSPECIFIED"        ",3,"
"^20,"   "ROOT"               ",2,"
"^21,"   "UNRESOLVED"         ",3"   EOS
 
//---------------------------------Expressions-----------------------------
"TKINDS" , A_CHAR("Entity Kind" )    EOS
"TNODE"  , A_CHAR("Index Node" )     EOS
 
// Constant identifiers
"EID0"   , A_CHAR( "Dir"                " I 3"     ),
"EID1"   , A_CHAR( "File"               " I 3"     ),
"EID2"   , A_CHAR( "Page"               " I 4"     ),
"EID3"   , A_CHAR( "Group"              " I 1"     ),
"EID4"   , A_CHAR( "DocAnchor"          " I 1 1"   ),
"EID5"   , A_CHAR( "NameSpace"          " I 1 1"   ),
"EID6"   , A_CHAR( "Struct"             " I 4"     ),
"EID7"   , A_CHAR( "Class"              " I 1"     ),
"EID8"   , A_CHAR( "Union"              " I 1"     ),
"EID9"   , A_CHAR( "ConCept"            " I 1 1"   ),
"EID10"  , A_CHAR( "Macro"              " I 1"     ),
"EID11"  , A_CHAR( "TypeDef"            " I 1"     ),
"EID12"  , A_CHAR( "Variable"           " I 1"     ),
"EID13"  , A_CHAR( "Function"           " I 1"     ),
"EID14"  , A_CHAR( "Enumeration"        " I 1"     ),
"EID15"  , A_CHAR( "EnumValue"          " I 1 1"   ),
"EID16"  , A_CHAR( "GenericMember"      " I 1 1"   ),
"EID17"  , A_CHAR( "Record"             " I 1"     ),
"EID18"  , A_CHAR( "UnSpecified"        " I 1 1"   ),
 
// Function names
"EID19"  , A_CHAR( "LinkString"              " I 1 1"         ),
"EID20"  , A_CHAR( "Display"                 " I 1"           ),
"EID21"  , A_CHAR( "Kind"                    " I 1"           ),
"EID22"  , A_CHAR( "Target"                  " I 1"           ),
"EID23"  , A_CHAR( "Name"                    " I 1"           ),
"EID24"  , A_CHAR( "Path"                    " I 4"           ),
"EID25"  , A_CHAR( "Parent"                  " I 1"           ),
"EID26"  , A_CHAR( "IsGood"                  " I 1 1"         ),
"EID27"  , A_CHAR( "IsResolved"              " I 1 1"         ),
"EID28"  , A_CHAR( "HasError"                " I 1 1"         ),
"EID29"  , A_CHAR( "HasWarning"              " I 1 1"         ),
"EID30"  , A_CHAR( "ErrorCode"               " I 1 1"         ),
"EID31"  , A_CHAR( "CountScopeHints"         " I 1 1 1"       ),
"EID32"  , A_CHAR( "ScopeHint"               " I 1 1"         ),
"EID33"  , A_CHAR( "CountScope"              " I 1 1"         ),
"EID34"  , A_CHAR( "Scope"                   " I 1"           ),
"EID35"  , A_CHAR( "Identifier"              " I 1"           ),
"EID36"  , A_CHAR( "CountParaMS"             " I 1 1 1 0"     ),
"EID37"  , A_CHAR( "ParaMS"                  " I 1 1 0"       ),
"EID38"  , A_CHAR( "CountTemplateParaMS"     " I 1 1 1 1 0"   ),
"EID39"  , A_CHAR( "TemplateParaMS"          " I 1 1 1 0"     ),
"EID40"  , A_CHAR( "CountTemplateSpecParaMS" " I 1 1 1 1 1 0" ),
"EID41"  , A_CHAR( "TemplateSpecParaMS"      " I 1 1 1 1 0"   ),
"EID42"  , A_CHAR( "LinkDisplay"             " I 1 1"         ),
"EID43"  , A_CHAR( "LinkTarget"              " I 1 1"         ),
"EID44"  , A_CHAR( "KindSpec"                " I 1 1"         ),
"EID45"  , A_CHAR( "Depth"                   " I 3"           ),
"EID46"  , A_CHAR( "TagFilePath"             " I 1 1 1"       ),
"EID47"  , A_CHAR( "TagFileName"             " I 1 1 1"       ),
"EID48"  , A_CHAR( "TagFileLine"             " I 1 1 1"       ),
"EID49"  , A_CHAR( "HtmlFile"                " I 4 1"         ),
"EID50"  , A_CHAR( "HtmlAnchor"              " I 4 1"         ),
"EID51"  , A_CHAR( "CountSourceLocationS"    " I 1 1 1 0"     ),
"EID52"  , A_CHAR( "CountHtmlLocationS"      " I 1 1 1 0"     ),
"EID53"  , A_CHAR( "IsScannedHtmlFile"       " I 1 1 1 1"     ),
"EID54"  , A_CHAR( "IsIndirectSourceFile"    " I 1 1 1 1"     ),
"EID55"  , A_CHAR( "IsInherited"             " I 1 1"         ),
"EID56"  , A_CHAR( "IsIndirectTypeDefMember" " I 1 1 1 1 1"   ),
"EID57"  , A_CHAR( "IsIndirectTypeDef"       " I 1 1 1 1"     ),
 
//------------------------------------------- Exceptions -------------------------------------------
"E<", "Exceptions::",
"E",  "1,ErrorOpeningFile"             ",ED1"
     ",2,UnknownKind"                  ",ED2"
    ",10,XMLSyntaxError"               ",ED10"
    ",11,NotATagStart"                 ",ED11"
    ",12,UnexpectedXMLTag"             ",ED12"
    ",13,XMLEndTagNotInSameLine"       ",ED13"
    ",14,FileNotOnRootLevel"           ",ED14"
    ",15,DuplicateChildName"           ",ED15"
    ",16,DuplicateCompound"            ",ED16"
    ",17,UnexpectedXMLValue"           ",ED17"
EOS
 
"ED1",   "Error opening {}file {!Q}."                      EOS
"ED2",   "Unknown kind found @ {}:{} XML: {!Q} found."        EOS
"ED10",  "XML Syntax error @ {}:{} XML: {!Q}"        EOS
"ED11",  "Expected a start of a tag @ {}:{} XML: {!Q}"        EOS
"ED12",  "Unexpected XML-tag @ {}:{} Expected: <{!Q}> Given: {!Q}"        EOS
"ED13",  "XML end-tag not found in same line @ {}:{} Expected: \"</{}>\" Given: {!Q}"        EOS
"ED14",  "File-Compound not on root level of XML file @ {}:{}"        EOS
"ED15",  "Duplicate member name {!Q} in path {!Q}\n"
         "   First definition:  @ {}:{}\n"
         "   Second definition: @ {2}:{}"        EOS
"ED16",  "Duplicate compound {!Q}\n"
         "   First definition:  @ {}:{}\n"
         "   Second definition: @ {1}:{}"        EOS
"ED17",  "Unexpected value in XML tag @ {}:{} Expected: <{!Q}> Given: {!Q}"        EOS
 
 
//-------------------------------------- XL Error/Warning texts ------------------------------------
"XL_ERR_0", "OK"                                                                                 EOS
"XL_ERR_1", "Too many parents requested to be displayed"                                         EOS
"XL_ERR_2", "An anchor without a title was used without providing a user-defined display string.\n"
            "DoxygenXLinks (like Doxygen itself) inserts the anchor name in this case.\n"
            "To mitigate this warning, add \";1\" to the link or add a reasonable display string." EOS
"XL_ERR_3", "A display tweak was given that is not applicable to the resolved target type"       EOS
"XL_ERR_5", "The search string is empty (apart from possible whitespaces)."                      EOS
"XL_ERR_6", "No target identifier found."                                                        EOS
"XL_ERR_7", "Too many scope-hints (words separated with spaces) were given."                     EOS
"XL_ERR_8", "The number of nested scope (namespaces/compounds) is too huge to be processed by DoxygenXLinks (the maximum is 20)" EOS
"XL_ERR_9", "The underlying type requested with '^' was not found."                              EOS
"XL_ERR_10","Unknown kind type requested with '!', or missing space after kind. Allowed type kinds are:\n"  // todo: the '!' is wrong
            "  'd'=directory, 'f'=file, 'p'=Macro, 'n'=Namespace,'c'=Concept, 't'=Typedef 'r'=RECORD, 'c'=class, \n"
            "  's'=struct, 'u'=union, 'e'=Enumeration 'a'=Enum element 'm'=Function, 'v'=Variable" EOS
"XL_ERR_11","A local link (aka the identifier section starts with '.') must not have scope hints." EOS
"XL_ERR_12","This error is set, with the command line option '--doxyfy'.\n"
            "As explained in the user manual, equal local links cannot be restored back to\n"
            "Doxygen's \\\\ref command if they occur in different HTML files. Please check each\n"
            "location below and manually correct the link to target the right local entitiy."    EOS
"XL_ERR_13","This error is set, with the command line option '--doxyfy'.\n"
            "It occurs when a local link is found in the source-copy to be restored, which has not\n"
            "been found in the HTML files.\n"
            "This usually indicates an erroneous setup of the documentation build-steps."        EOS
 
 
//------------------------------------------- Variables --------------------------------------------
//------------------------------------------ Config files ------------------------------------------
"CFGF_NAME_1"     , ALIB_REL_DBG( "DoxygenXLinks.ini",
                                  "DoxygenXLinks.ini" ),
"CFGF_NAME_2"   , ALIB_REL_DBG( "DoxygenXLinks.alib.ini",
                                "DoxygenXLinks.alib.ini" ),
 
"CFGF_EXP_1" , "/",
"CFGF_EXP_2" , "ALIB,ALOX",
 
 
"CFGF_CMT_1",
"@>'# '"
"@HL="
"DoxygenXLinks Configuration File\n"
"(c) 2025-2026 AWorx GmbH. Published under MIT License (Open Source).\n"
"@HL-\n"
"Notes:\n\n@*>"
"All configuration may also be set using environment variables or command-line parameters. "
"In this case, such settings 'overrule' those of this INI-File. (While command-line "
"arguments overrule environment variables.)@P\n"
 
"Variable values can be substituted using ${VARIABLE_NAME}. This allows to add custom "
"variables and assemble defined variables with the custom ones. For an example, see variable "
"\"DL_LOGFILE_VERBOSITY\" below (section [DL], name \"LOGFILE_VERBOSITY\").@P\n"
 
"Sections [ALIB] and [ALOX] are used by underlying libraries the DoxygenXLinks is build on. "
"By default, these sections reside in (this) main INI-file. It is however possible to "
"separate the two sections into a different file to reduce clutter. "
"(Invoke 'DoxygenXLinks -h=config' for options on this).@P@P"
"ALox is the logging system that the DoxygenXLinks uses to produce log output. For more information on how"
"to leverage the variables exposed in these sections, refer to:@P"
"   http://alexworx.github.io/ALox-Logging-Library/group__GrpALoxConfigVars.html @P\n"
 
"If this INI-file gets deleted (or partly deleted) all built-in default sections, variables, "
"values and comments will be freshly written on the next invocation of DoxygenXLinks.  "
 
"@<*"
"@HL=" EOS
 
"CFGF_CMT_2",
"@>'# '"
"@HL="
"DoxygenXLinks Configuration File for underlying libraries ALib and ALox\n"
"(c) 2025-2026 AWorx GmbH. Published under MIT License (Open Source).\n"
"@HL-\n"
"Note:\n"
"@>>"
"This is a separated, secondary configuration file of the DoxygenXLinks software, containing "
"mainly variables of the underlying logging system ALox.\n"
"To leverage the variables exposed in this file, refer to:\n"
"  https://alib.dev/alib_alox_cfgvars.html\n"
"By default, the name of the main configuration file is 'DoxygenXLinks.ini'.\n"
"@<<"
"@HL="
EOS
 
 
//-------------------------------------------------------------------------------------------------
//------------------------------------------- CLI --------------------------------------------
//-------------------------------------------------------------------------------------------------
 
//------------------------------------------- CLI Commands --------------------------------------------
"DLCmds<", "Commands::",
"DLCmds",
//enum     ident        minread     Params
"1,"    "clean"         ",1"        ",PD"         EOS
 
"THlpCmdSht_clean",  A_CHAR("Reports the actual date/time"),
"THlpCmdLng_clean",  A_CHAR("Reports the actual date/time. May be omitted, as this is the\n"
                            "default if no command is given.")                         EOS
 
 
 
//------------------------------------------- CLI Options --------------------------------------------
"DLOptions<", "Options::",
"DLOptions",
//enum  ident        minread    identChar   in-arg-separ.   args to consume    ShortcutTo
""    EOS
 
 
//------------------------------------------- CLI Parameters --------------------------------------------
"DLParams",
 
//enum  name       minIdentLen   identifier          in-arg-sep   delim   args to consume  isOptional
//                               (if empty -> mandatory!)
"1,"  "PD"         ",1,"         ""          ","     "="         ","      ",-1"            ",1"  EOS
 
"DLParams<", "Parameters::",
 
//----------------------------------------- Exit Codes -----------------------------------------
"DLExitCodes",
//enum  name                             assoc. cli exception
"0,"   "OK"                                ",-1,"
"20,"  "CantOpenDoxyfile"                  ",-1,"
"21,"  "NoTagfileGeneratedByDoxyfile"      ",-1,"
"22,"  "OtherErrorInDoxyfile"              ",-1,"
"23,"  "TagFileNotFound"                   ",-1,"
"24,"  "NoHTMLFilesFound"                  ",-1,"
"25,"  "CantOpenHMLFile"                   ",-1,"
"26,"  "CantWriteHMLFile"                  ",-1,"
"27,"  "NoSourceFilesFound"                ",-1,"
"28,"  "CantOpenSrcFile"                   ",-1,"
"29,"  "NoSourceCopiesFound"               ",-1,"
"30,"  "CantOpenReplSrcFile"               ",-1,"
"31,"  "CantWriteReplSrcFile"              ",-1,"
"32,"  "NoReplacementSourceFiles"          ",-1"   EOS
 
"DLExitCodes<", "ExitCodes::"
 
,"TExit20",  "Doxygen (INI-)file {!Q} not found or not accessible."
,"TExit21",  "Entry GENERATE_TAGFILE needs to be set in {!Q} to enable DoxygenXLinks."
,"TExit22",  "Error parsing the Doxygen file {!Q}. Details: {}"
,"TExit23",  "The tag-file {!Q} specified in the Doxygen (INI-)file {!Q} was not found."
,"TExit24",  "No Doxygen output files with extension {!Q} found in directory {!Q}"
,"TExit25",  "Cannot open HTML file {!Q} (maybe not accessible)."
,"TExit26",  "Cannot write HTML file {!Q} (Error code {})."
,"TExit27",  "Did not find any source file with the specifications given in doxyfile {!Q}."
,"TExit28",  "Cannot open source file {!Q} (maybe not accessible)."
,"TExit29",  "Did not find any copy of source files in folder {!Q} given with option --doxyfy."
,"TExit30",  "Cannot open replacement source {!Q} (maybe not accessible)."
,"TExit31",  "Cannot write replacement source file {!Q} (Error code {})."
EOS
 
//------------------------------------------- CLI Help Texts --------------------------------------------
"HlpGeneral",
"\nABOUT DoxygenXLinks\n"
"@>>"
"This is a command-line interface..."
"\n@<<\n"
 
EOS
 
    // end of BootstrapBulk()
    nullptr );
 
    //---- replace some default values of ALOX variables ----
    {
        ResourcePool&       pool    = ALOX.GetResourcePool();
        NCString&           category= ALOX.ResourceCategory;
        #if ALIB_DEBUG
        #   define             errMsg    "Error: Incompatible ALox resource string found. Update your code to current ALib version."
        #endif
 
        ALIB_ASSERT_ERROR( pool.Get(category, "Var2" ALIB_DBG(,true)).Equals("3|ALOX/%2/VERBOSITY_WITH_%1|ALOXV"), "DLCLI", errMsg )
        pool.BootstrapAddOrReplace( category, "Var2",                        "3|ALOX/%2/VERBOSITY|ALOXV"   );
        pool.BootstrapAddOrReplace( category, "Var_D3",                      "${VERBOSITIES/DEFAULT}"    );
    }
 
    #if ALIB_DEBUG
    #   undef  errMsg
    #endif
}
void DXLApp::onBsPrepareConfig() {
    // call parent's implementation. This bulk-loads the resources into the camps.
    AppCli::onBsPrepareConfig();
 
//    enumrecords::bootstrap::Bootstrap<Commands   >();
//    enumrecords::bootstrap::Bootstrap<Parameters >();
//    enumrecords::bootstrap::Bootstrap<Options    >();
    enumrecords::bootstrap::Bootstrap<ExitCodes  >();
    enumrecords::bootstrap::Bootstrap<Target::Kinds  >();
 
 
    //-------------------------------- BootstrapPhases::PrepareConfig ------------------------------
    ALIB_BOXING_BOOTSTRAP_REGISTER_FAPPEND_FOR_APPENDABLE_TYPE( ExitCodes  )
    ALIB_BOXING_BOOTSTRAP_REGISTER_FAPPEND_FOR_APPENDABLE_TYPE( dxl::Exceptions )
    ALIB_BOXING_BOOTSTRAP_REGISTER_FAPPEND_FOR_APPENDABLE_TYPE( Target::Kinds )
 
    namespace erb= alib::enumrecords::bootstrap;
    erb::Bootstrap<dxl::Exceptions>();
//      erb::Bootstrap<VerbosityPresets>( '|' );
 
    #if ALIB_DEBUG
 
    // todo: vielleicht sollte man für sowas ein extra DBGPreparations in alib::App machen?
    //       einfach damits aufgeräumt ist? Und der user, wenn er über die Reference doku geht
    //       und sich die States ansieht, dort den Hinweis bekommt? Und man könnte ja dort auch
    //       gleich beispielhaft die enums der app registrieren.
    assert::RegisterPrintable(typeid(Target::Kinds), [](const std::any& any, std::string& s) {
        s+= NString256(std::any_cast<Target::Kinds>(any));
    });
    #endif
}
 
alib::Enum  DXLApp::exceptionToExitCode( alib::Exception& e ) {
    // check with parent
    Enum result= App::exceptionToExitCode(e);
 
    // handle cli-exceptions
    if (   result == BuiltInExitCodes::ErrUnknown
        && e.Type().IsEnumType<cli::Exceptions>() ) {
        auto element= e.Type().Get<cli::Exceptions>();
        for( auto& exitCodeDecl : cli.ExitCodeDecls )
            if( exitCodeDecl.second->AssociatedCLIException() == element ) {
                result= exitCodeDecl.first;
                break;
    }       }
 
    // also, we do not know. This is not good!
    return result;
}
 
 
 
void DXLApp::onBsSetNameVersionAndInfo() {
    String infoFmtString= APPCLI_CAMP.GetResource("AppVersion");
    String128 buffer;
    ALIB_LOCK_RECURSIVE_WITH(alib::format::Formatter::DEFAULT_LOCK)
        Formatter::DEFAULT->Format( buffer, infoFmtString, alib::VERSION, alib::REVISION );
        appVersion= String(monomem::GLOBAL_ALLOCATOR, buffer);
 
    AppCli::onBsSetNameVersionAndInfo();
}
 
void DXLApp::bsCLIDefine() {
    AppCli::bsCLIDefine();
    cli.DefineExitCodes <enum ExitCodes >();
//    cli.DefineParameters<enum Parameters>();
//    cli.DefineCommands  <enum Commands  >();
//    cli.DefineOptions   <enum Options   >();
}
 
 
bool DXLApp::cliProcessCmd(cli::Command* cmd) {
    if ( AppCli::cliProcessCmd(cmd) )
        return true;
 
    if ( cmd == nullptr ) {
        if (cli.ArgsLeft.size() == 0) {
            ALIB_ERROR("DLX", "NIY: error output that no doxyfile given")
        }
        DoxyfilePath= cli.PopArg();
        dxl= new DoxygenXLinks();
        dxl->Run();
        return true;
    }
 
    return false;
}
 
 
void DXLApp::onRunEnd() {
    AppCli::onRunEnd();
    if (dxl) {
        dxl->TPool.WaitForAllIdle(10min ALIB_DBG(, 5s) );
        dxl->TPool.Shutdown();
        delete dxl;
        dxl= nullptr;
    }
 
}
 
 
} //namespace [dxl]
 
#include "ALib.Lang.CIFunctions.H"
// #################################################################################################
// main()
// #################################################################################################
int main( int argc, const char** argv) {
    return dxl::DXLApp().Main(argc, argv);
}
#include "ALib.Lang.CIMethods.H"