xlink.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 "xlink.hpp"
#include "target.hpp"
#include "dxl.hpp"
#include "expressions/expressionscamp.inl"
 
using namespace alib;
using namespace std;
 
namespace dxl {
 
// todo: Add "?" to enable debug output: This just lists All entities found with that name.
//       Allow \? to escape the question mark.
 
void XLink::Parse() {
    Substring searchString= LinkString;
 
    searchString.TrimEnd();
    DisplayOriginalPos= searchString.Length();
 
    // ------------------------------ consume prefixes  ------------------------------
    if (searchString.ConsumeChar<lang::Case::Sensitive, lang::Whitespaces::Trim>('^'))
        NoIndirectionWarning= true;
 
    char kindSpecChar= 0;
    if ( searchString.Length() > 1 && searchString.CharAt<NC>(1) == ';') {
        kindSpecChar= searchString.CharAt<NC>(0);
        searchString.ConsumeChars<NC>(2);
    }
    if (searchString.ConsumeChar<lang::Case::Sensitive, lang::Whitespaces::Trim>('^'))
        NoIndirectionWarning= true;
 
    // interpret kind spec character
    switch (tolower(kindSpecChar)) {
        case'\0': KindSpec= Target::UNSPECIFIED;    break;
        case 'd': KindSpec= Target::Dir;            break;
        case 'f': KindSpec= Target::File;           break;
        case 'p': KindSpec= Target::Macro;          break;
        case 'n': KindSpec= Target::Namespace;      break;
        case 'o': KindSpec= Target::Concept;        break;
        case 't': KindSpec= Target::Typedef;        break;
        case 'r': KindSpec= Target::RECORD;         break;
        case 'c': KindSpec= Target::Class;          break;
        case 's': KindSpec= Target::Struct;         break;
        case 'u': KindSpec= Target::Union;          break;
        case 'e': KindSpec= Target::Enumeration;    break;
        case 'a': KindSpec= Target::EnumElement;    break;
        case 'm': KindSpec= Target::Function;       break;
        case 'v': KindSpec= Target::Variable;       break;
        default: Error= Errors::IllegalTargetKind;  return;
    }
 
    // correct original Display position in search string (will be corrected once more)
    DisplayOriginalPos-= searchString.Length();
 
    // has display? If yes, cut that first from the end
    integer displayStart= searchString.LastIndexOf(';');
    if (displayStart>=0) {
        DisplayOriginalPos+= displayStart + 1;
        Substring display(searchString.Substring(displayStart + 1));
        searchString.ConsumeCharsFromEnd(display.Length() + 1);
        searchString.TrimEnd();
        display.TrimEnd();
        if (integer pos= display.IndexOf("\\\""); pos>=0) {
            String256 tmpDisplay(display);
            tmpDisplay.SearchAndReplace("\\\"", "\"", pos);
            Display= String(MA, tmpDisplay);
        }
        else
            Display= String(MA, display);
    }
    else
        DisplayOriginalPos= 0;
 
    if (searchString.IsEmpty()) {
        Error= Errors::Empty;
        return;
    }
 
    // scan dir/file link
    if (HasOneOf(KindSpec, Target::Dir|Target::File) ) {
        String tmpScope[MAX_SCOPE_DEPTH];
 
        scopeHintsSize=
        scopeSize     = 0;
 
        // consume search string word by word (space separated)
        while ( searchString.TrimStart().IsNotEmpty() ) {
            if (scopeSize == MAX_SCOPE_DEPTH - 1) {
                Error = Errors::ScopeTooDeep;
                return;
            }
 
            //
            String128 word;
            if (searchString.ConsumeChar('\'')) {
                while (searchString.IsNotEmpty()) {
                    if (searchString.ConsumeChar('\\')) {
                        if (searchString.IsNotEmpty())
                            word._<NC>(searchString.ConsumeChar());
                        continue;
                    }
                    if (searchString.ConsumeChar('\''))
                        break;
                    word._<NC>(searchString.ConsumeChar());
                }
            } else {
                while (searchString.IsNotEmpty() && searchString.CharAtStart() != ' ') {
                    if (searchString.ConsumeChar('\\')) {
                        if (searchString.IsNotEmpty())
                            word._<NC>(searchString.ConsumeChar());
                        continue;
                    }
                    word._<NC>(searchString.ConsumeChar());
                }
            }
 
            tmpScope[scopeSize++] = String(MA, word);
            if (searchString.CharAtStart() == ' ')
                scopeHintsSize = scopeSize;
        }
 
        if (scopeSize == 0) { Error = Errors::NoTargetNameGiven; }
 
        // if the last component name ended with a space, we need to steal one hint and add it to the
        // scope components.
        if (scopeHintsSize == scopeSize)
            --scopeHintsSize;
 
        // split the name into path components
        ALIB_ASSERT(scopeSize == scopeHintsSize + 1, "DXL/PARSE")
        for (;;) {
            // find '/' or stupid windows backslash '\'
            integer nextPos= tmpScope[scopeSize-1].IndexOfOrLength('/');
            nextPos= std::min(nextPos, tmpScope[scopeSize-1].IndexOfOrLength('\\'));
            if (nextPos== tmpScope[scopeSize-1].Length())
                break;
            tmpScope[scopeSize  ]= tmpScope[scopeSize-1].Substring(nextPos + 1);
            tmpScope[scopeSize-1]= tmpScope[scopeSize-1].Substring(0, nextPos);
            ++scopeSize;
            if (scopeSize==MAX_SCOPE_DEPTH) {
                Error= Errors::ScopeTooDeep;
                return;
            }
        }
        // copy the local array to our member
        scope= MA().NewArray<String>(scopeSize);
        for (integer i= 0; i < scopeSize; ++i)
            scope[i]= tmpScope[i];
 
        return;
    }
 
    // ------------------------------ parse code-targets ------------------------------
    // starts with keyword "template" ?
    if ( searchString.StartsWith("template") ) {
        if (searchString.CharAt(8) == ' ' ) {
            searchString.ConsumeChars(9);
            searchString.TrimStart();
 
            // keyword "template " given, but no arguments -> create empty arguments
            if (searchString.CharAtStart()!='<')
                TemplateArgs= MA().New<Target::TemplateArguments>();
 
        } else if (searchString.CharAt(8) == '<' ) {
            searchString.ConsumeChars(8);
        }
    }
 
    // starts with (or at least now after template keyword) template args?
    if (searchString.CharAtStart() == '<' ) {
        // todo: it hast to be tested
        // - if the search string is rightfully cut
        // - what happens if no closing '>' is given.
        //   (probably a crash. At least we got to set a parse error, which we never used, yet,
        //    an important todo. Parse errors have to be displayed in the output!)
        // - do path hints still work? Does the XLink need to be "template<> str TString"?
        TemplateArgs= Target::TemplateArguments::PARSE(MA, searchString.TrimStart());
    }
 
    // helper to read the next identifier including template params
    auto getNextIdentiferWithTemplateArgs = [&](Substring& src, String& word) {
        String orig= src;
        int templateDepth= 0;
 
        // read identifier up to template or sth different
        if ( src.StartsWith("operator")) {
            src.ConsumeChars(8);
            src.TrimStart();
            if (   !src.ConsumeString("()")
                && !src.ConsumeString("bool") )
                src.TrimStart("+-*/&%|~^=!<>[]");
         } else {
            while (isalnum(src.CharAtStart()) || src.CharAtStart() == '_')
                src.ConsumeChar<NC>();
 
            while (src.IsNotEmpty()) {
                if (src.ConsumeChar('<')) {++templateDepth; continue;}
                if (src.ConsumeChar('>') && --templateDepth == 0)
                    break;
                if (templateDepth > 0 ) {
                    src.ConsumeChar();
                    continue;
                }
                break;
            }
        }
 
        word= orig.Substring(0, orig.Length() - src.Length());
    };
 
    // read all identifiers (scope hints and scope)
    {
        String tmpScope[MAX_SCOPE_DEPTH];
        scopeHintsSize=
        scopeSize     = 0;
        IsLocal       = searchString.TrimStart().ConsumeChar('.');
 
        for (;searchString.TrimStart().IsNotEmpty();) {
            String word;
            getNextIdentiferWithTemplateArgs(searchString, word);
            if (word.IsEmpty()) {
                if(searchString.CharAtStart()=='.') {
                    IsLocal= true; // this will lead to an error below: local with path hints
                    searchString.ConsumeChar();
                    continue;
                }
                break; // happens when non-alnum characters are given
            }
            if (scopeSize==MAX_SCOPE_DEPTH-1) {
                Error= Errors::ScopeTooDeep;
                return;
            }
            tmpScope[scopeSize++]= String(MA, word);
            if (searchString.CharAtStart() == ' ')
                scopeHintsSize= scopeSize;
            else {
                searchString.ConsumeChar('.');
                searchString.ConsumeChar(':');
                searchString.ConsumeChar(':');
            }
        }
 
        // if the last component name ended with a space, we need to steal one hint and add it to the
        // scope components.
        if (scopeHintsSize == scopeSize)
            --scopeHintsSize;
 
        // copy the local array to our member
        if (scopeSize>0) {
            scope= MA().NewArray<String>(scopeSize);
            for (int i= 0; i < scopeSize; ++i)
                scope[i]= tmpScope[i];
        } else {
            Error= Errors::NoTargetNameGiven;
            return;
        }
 
        // if a local link is given, no scope hints are accepted
        if (IsLocal && scopeHintsSize > 0) {
            Error= Errors::LocalLinkWithScopeHints;
            return;
        }
    } // end of reading scope
 
    // parse subscript
    searchString.TrimStart();
    if (searchString.ConsumeChar('[')) {
        String128 subscript;
        int depth= 0;
        while ( depth > 0 || !searchString.ConsumeChar(']') ) {
            if (searchString.ConsumeChar('[')) ++depth;
            if (searchString.ConsumeChar(']')) --depth;
            subscript._<NC>(searchString.ConsumeChar());
        }
        Subscript= String(MA, subscript);
        searchString.TrimStart();
    }
 
    // parse template-specialization arguments (they come AFTER the identifier name)
    integer templateStart= scope[scopeSize-1].IndexOf('<');
    if (templateStart == 8 && scope[scopeSize-1].StartsWith("operator") ) {
        if (scope[scopeSize-1].CharAt(9) == '<') // operator<<
            templateStart= 9;
        templateStart= scope[scopeSize-1].IndexOf('<', templateStart + 1);
    }
    if (templateStart>=0) {
        Substring templateParams= scope[scopeSize-1].Substring(templateStart);
        scope[scopeSize-1]= scope[scopeSize-1].Substring(0, templateStart);
 
        SpecializationArgs= Target::TemplateArguments::PARSE(MA, templateParams);
    }
 
    // parse function arguments
    if (searchString.CharAtStart() == '(')
        Args= Target::FunctionArguments::PARSE(MA, searchString);
 
    // qualifiers?
    if(searchString.Trim().IsNotEmpty())
         Qualifiers= String( MA, searchString);
}
 
XLink* XLink::GetLinkToParent() {
    // create only once
    if ( linkToParentScope )
        return linkToParentScope;
 
    // create a dummy-XLink to search for possible parent nodes
    linkToParentScope= MA().New<XLink>();
    ALIB_DBG( linkToParentScope->MA.DbgCriticalSectionsPH->DCSLock= nullptr;)
 
    // non-local links: create the parent scope
    if(!IsLocal) {
        linkToParentScope->scope= MA().NewArray<String>(scopeSize-1);
        for (int i= 0; i < scopeSize-1; ++i)
            linkToParentScope->scope[i]= scope[i];
        linkToParentScope->scopeSize     = scopeSize - 1;
        linkToParentScope->scopeHintsSize= scopeHintsSize;
 
        // search the XLink
        for (auto* index : app::Get<DXLApp>().dxl->Indices )
            index->Search(*linkToParentScope);
    }
    // local links: we can (almost) directly put the parent to the result-list of the dummy link
    else {
        Index* mainIndex= app::Get<DXLApp>().dxl->Indices.back();
        Index::Node node= mainIndex->ImportNode(Index::CursorHandle{LocalLinkEntity.value});
        bool scopeFound= true;
        { ALIB_LOCK_SHARED_WITH(mainIndex->SLock)
            for(int i= 0; i < scopeSize-1; ++i)
                if(!node.AsCursor().GoToChild(Scope(i)) ) {
                    // if the child node does not exist, then we just do not add anything
                    // and no result is generated
                    scopeFound= false;
                    break;
                }
        }
 
        if(scopeFound)
            linkToParentScope->Targets.push_back({  node
                                                  , mainIndex->BaseURL
                                                  , node.HTMLFile()
                                                  , EMPTY_STRING
                                                  ,false,false,false,false,false,false,false
                                                });
    }
 
    // loop over all possible scope-parents
    for ( Index::SearchResult& scopeParent : linkToParentScope->Targets ) {
        // collect all parents from all possible records. This is done in a BFS per
        // possible parent. This means, we go into the breadth, but per parent.
        if ( auto* rec= Cast<TGTRecord>(scopeParent.Node); rec )
            findInherited( rec->BaseTypes );
 
        // if this scope-parent was a type definition, we follow those
        else if ( scopeParent.Node.IsA(Target::Typedef)) {
 
            // search final (!) target (could be chained type-defintions)
            if ( Index::Node targetCursor= ResolveTypeDef(scopeParent.Node, LinkString);
                 !targetCursor.IsRoot() ) {
                // great, we found the original component.
                if (!TypeDefinitionTargets)
                    TypeDefinitionTargets= MA().New<ListMA<Index::Node>>(MA);
                TypeDefinitionTargets->push_back(targetCursor);
            }
        }
    } // loop over possible parents
 
    // now we also have to add the base types of the type definition targets to the parents!
    // (wow). But it seems like we do not need to do the opposite: Doxygen Tag files
    // provide resolved type definitions in its list of base-types.
    if ( TypeDefinitionTargets ) {
        for (auto& typeDefTargetCursor : *TypeDefinitionTargets)
            if ( auto* rec= Cast<TGTRecord>(typeDefTargetCursor); rec)
                findInherited( rec->BaseTypes );
    }
 
    // logging base types found
    if ( BaseTypes ) {
        int cntLoggers; Lox_IsActive(cntLoggers, Verbosity::Info, "DXL/INDIRECT")
        if (cntLoggers > 0) {
            String1K parentLog;
            for (auto& p : *BaseTypes)
                parentLog << "  " <<  p.Name() << NEW_LINE;
            Lox_Info("DXL/INDIRECT", "Potential parents of XLink {!Q} are\n{}",
                      LinkString, parentLog)
        }
    }
 
    return linkToParentScope;
}
 
#include "ALib.Lang.CIFunctions.H"
Index::Node XLink::ResolveTypeDef( const Index::Node& startCursor,
                                     const alib::String&  origSearchString ) {
 
    // search final (!) target (could be chained type-defintions)
    Index::Node typeDefCursor= startCursor;
    for (;;) {
        const TGTTypedef& typeDef= *Cast<TGTTypedef,NC>(typeDefCursor);
        Lox_Info("DXL/INDIRECT", "Type definition for {} found: {}", origSearchString, typeDef.Type)
 
        // search in indices
        Index::Node typeDefTargetCursor;
        for ( auto* index : app::Get<DXLApp>().dxl->Indices  ) {
            // create base type path
            String512 typeDefPath(typeDef.Type);
            typeDefPath.ShortenTo(typeDefPath.IndexOfOrLength('<'));
            index->ReplaceToTreeSeparator(typeDefPath, Target::Typedef);
            {ALIB_LOCK_SHARED_WITH(index->SLock)
                if ( (typeDefTargetCursor= index->Root()).AsCursor().GoTo(typeDefPath).IsEmpty() )
                    break;
            }
            typeDefTargetCursor= index->Root();
        }
        // if not found, this probably is a namespace-local
        if (typeDefTargetCursor.IsRoot()) {
            Index::Node scopeParentCursor= typeDefCursor.Parent();
            String512 typeDefPath(typeDef.Type);
            typeDefPath.ShortenTo(typeDefPath.IndexOfOrLength('<'));
            typeDefCursor.Index().ReplaceToTreeSeparator(typeDefPath, Target::Typedef);
            {ALIB_LOCK_SHARED_WITH(typeDefCursor.Index().SLock)
                while (!scopeParentCursor.IsRoot()) {
                    if((typeDefTargetCursor= scopeParentCursor).AsCursor().GoTo(typeDefPath).IsEmpty() )
                        break;
                    auto newScopeParentCursor= typeDefTargetCursor.Parent();
                    typeDefTargetCursor.AsCursor().GoToRoot();
                    if( newScopeParentCursor == scopeParentCursor )
                        break;
                    scopeParentCursor= newScopeParentCursor;
            }
        }   }
 
        if (typeDefTargetCursor.IsRoot()) {
            Lox_Info("The type definition {!Q} was not found in the tag file {}:1. "
                      "While processing XLink {!Q}. This is probably an inherited type definition "
                      "to be resolved later",
                      typeDef.Type, typeDefCursor.Index().FilePath, origSearchString )
            return typeDefTargetCursor;
        }
 
        // is again a type definition?
        if (typeDefTargetCursor.IsA(Target::Typedef)) {
            typeDefCursor= typeDefTargetCursor;
            continue;
        }
 
        // great, we found the original component.
        return typeDefTargetCursor;
    } // endless loop
}
#include "ALib.Lang.CIMethods.H"
 
void XLink::findInherited( const decltype(TGTRecord::BaseTypes)&         bases) {
 
    integer previousResultSize= BaseTypes ? BaseTypes->size() : 0;
    // first add all base types (bfs approach)
    for (auto& baseTypeName : bases) {
 
        bool found= false;
        for ( auto* index : app::Get<DXLApp>().dxl->Indices  ) {
            ALIB_LOCK_SHARED_WITH(index->SLock)
 
            // create base type path
            String512 baseTypePath(baseTypeName);
            integer templatePos= baseTypePath.IndexOfOrLength('<');
            baseTypePath.ShortenTo(templatePos);
            index->ReplaceToTreeSeparator(baseTypePath, Target::RECORD);
 
            // search
            Index::Node baseType;
            if ( (baseType= index->Root()).AsCursor().GoTo(baseTypePath).IsEmpty() ) {
                if (!baseType.IsA(Target::RECORD | Target::Typedef)) {
                    Lox_Error("The specified base entity {!Q} is not a record or a type defintion, but a {}. "
                              "Detected in tag-file {!Q}",
                               baseTypePath, baseType.Kind(), index->FilePath )
                    continue;
                }
 
                found= true;
                if (!BaseTypes)
                    BaseTypes= MA().New<ListMA<Index::Node>>(MA);
                BaseTypes->push_back(baseType);
            }
        }
 
        // not found? Should not happen!
        if (!found) {
            Lox_Error("The specified base entity {!Q} does not exist in any tag-file.", baseTypeName)
        }
    }
 
    // now search the grandparents of those that we have found (recursion)
    if (BaseTypes) {
        integer newResultSize= BaseTypes ? BaseTypes->size() : 0;
        integer i= 0;
        for ( auto& baseType : *BaseTypes ) {
            if ( i>= previousResultSize && i < newResultSize )
                findInherited( Cast<TGTRecord,NC>(baseType)->BaseTypes);
            ++i;
        }
    }
}
 
void XLink::AssembleDisplay() {
    const Index::SearchResult& result = Result();
    Index::Node        node   = result.Node;
    const Target*      target = node.Target();
 
    //-------------------- parse display ------------------
    Substring display= Display;
    bool starGiven      = false;
    bool addFArgs       = false;
    bool addTArgs       = false;
    bool addSubscript   = false;
    bool addType        = false;
    bool addQualifiers  = false;
    int  addParents     = 0;
    for (;;) {
        if (   display.ConsumeChar('/')   ) break;
        if (   display.ConsumeChar('<')
            || display.ConsumeChar('>')   ) { addTArgs      = true;                   continue; }
        if (   display.ConsumeChar('(')
            || display.ConsumeChar(')')   ) { addFArgs      = true;                   continue; }
        if (   display.ConsumeChar('[')
            || display.ConsumeChar(']')   ) { addSubscript  = true;                   continue; }
        if (   display.ConsumeChar('?')   ) { addType       = true;                   continue; }
        if (   display.ConsumeChar('!')   ) { addQualifiers = true;                   continue; }
        if (   display.ConsumeChar('*')   ) { starGiven     = true;                   continue; }
        if (isdigit(display.CharAtStart())) { addParents= display.ConsumeChar()-'0';  continue; }
        break;
    }
 
    if (starGiven)
        addFArgs= addTArgs= addSubscript= addType= addQualifiers= true;
 
 
    //-------------------------------------- docs ----------------------------------------
    if ( target->IsA(Target::DocAnchor | Target::Page | Target::Group) ) {
        CSSClasses.Set(node, display.IsNotEmpty(), false );
        const String& title= target->IsA(Target::DocAnchor) ? Cast<TGTDocAnchor, NC>(target)->Title
                            :target->IsA(Target::Page)      ? Cast<TGTPage     , NC>(target)->Title
                                                            : Cast<TGTGroup    , NC>(target)->Title;
        if (display.IsEmpty()) {
            if ( title.IsNotEmpty() ) {
                Display= title;
                return;
            }
                 if ( addParents == 0)  Error= Errors::AnchorHasNoTitle;
            else if ( addParents >  1)  Error= Errors::InappropriateDisplayTweak;
            Display= Name();
            return;
        }
        if ( !display.Equals(Display))
            Display= String(MA, display);
        return;
    }
 
    //-------------------------------------- Dir/File ----------------------------------------
    if ( target->IsA(Target::Dir | Target::File) ) {
        if ( addFArgs | addTArgs | addSubscript | addType | addQualifiers )
            Error= Errors::InappropriateDisplayTweak;
 
        CSSClasses.Set(node, display.IsNotEmpty(), false );
        if ( display.IsNotEmpty()) {
            if ( !display.Equals(Display))
                Display= String(MA, display);
            return;
        }
    }
 
    //-------------------------------------- Types ----------------------------------------
    else {
        CSSClasses.Set( node, display.IsNotEmpty(),    Result().IsIndirectByTypeDef
                                                    || Result().IsIndirectByInheritance
                                                    || Result().IsResolvedTypeDef        );
        ALIB_ASSERT(CSSClasses.Get(1).Equals("xl-entity"), "DXL/XLINK")
 
        if ( display.IsNotEmpty() && !addFArgs && !addTArgs && !addType && addParents < 2 ) {
            Display= display; // in case '/' was cut
            return;
        }
    }
 
    String256 newDisplay;
    newDisplay.DbgDisableBufferReplacementWarning();
 
    // add "template<...>" ? (done when * or keyword "template", or at least one
    // template argument was given)
    if ( auto* rec= Cast<TGTRecord>(target);
         rec && rec->TemplateArgs) {
        if(addTArgs || TemplateArgs ) {
            newDisplay._("template ");
            rec->TemplateArgs->Print(newDisplay);
            newDisplay._<NC>(' ');
        }
    }
 
    // add Type
    if ( addType ) {
        if ( auto* var= Cast<TGTVariable>(target); var)
            newDisplay << var->Type << ' ';
        if ( auto* func= Cast<TGTFunction>(target);
             func && func->Type.IsNotEmpty()) // may be empty for constructor
            newDisplay << func->Type << ' ';
    }
 
    // add parents?
    if (addParents && !target->IsA(Target::Macro)) {
        integer prevDisplayLength= newDisplay.Length();
 
        // if inherited or a resolved type definition, then the originally given parent path has
        // to be used.
        if (result.IsIndirectByInheritance || IsUnderlyingTypeDef) {
            for (int i= addParents-2 ; i>= 0; --i) {
                int parentIdx= ScopeSize() - i -1;
                if (parentIdx>=0){
                    newDisplay << Scope(parentIdx);
                    if (i>0)
                        newDisplay << "::";
                }
                else
                    Error= Errors::TooManyParentsRequested;
            }
        } else {
            // for some reason, the dir type in the tag file resides already in an according
            // parent folder
            auto n= node;
            if(KindSpec == Target::Dir)
                n= n.Parent();
            auto parent= n;
            int cntParentOverflow = 0;
            for (; cntParentOverflow < addParents && !parent.IsRoot(); ++cntParentOverflow)
                parent= parent.Parent();
            if ( parent.IsRoot() && cntParentOverflow < addParents)
                Error= XLink::Errors::TooManyParentsRequested;
            { ALIB_LOCK_SHARED_WITH(n.Index().SLock)
                n.Parent().Path(newDisplay, parent); }
        }
        // parent path added? -> add a separator
        if (prevDisplayLength != newDisplay.Length()){
            if (HasOneOf(KindSpec, Target::Dir|Target::File))
                newDisplay._<NC>(system::DIRECTORY_SEPARATOR);
            else
                newDisplay._<NC>("::");
        }
    }
 
    // add name
    newDisplay << Name();
 
    // we add all parameters in case the user gave them 100% correct (not as hints)
    // or qualifiers have been given.
    // or display was set to "*"
    if ( auto* func= Cast<TGTFunction>(target); func) {
        if (   addFArgs
            || addQualifiers
            || result.FunctionArgumentMatch==4
            || Qualifiers.IsNotEmpty() ) {
            if ( func->Args  ) func->Args->Print(newDisplay);
            else               newDisplay._("()");
        }
 
        // In case of qualifiers, all are added, even if just a hint was given.
        if (addQualifiers || result.QualifiersHintMatch) {
            newDisplay._<NC>(' ')._<NC>(func->Qualifiers);
            // nevertheless, "noexcept" is removed. In V6501 this will be configurable :-)
            if (newDisplay.EndsWith("noexcept") )
                newDisplay.ShortenBy(8);
            display.TrimEnd();
    }   }
 
    // For prepro macros, we add all parameters in case the user just gave them
    if (   target->IsA(Target::Macro)
        && (Args || (addFArgs && Cast<TGTMacro,NC>(target)->Args) ) ) {
        Cast<TGTMacro,NC>(target)->Args->Print(newDisplay);
    }
    // add template specialization? (done when <,>, *, or at least one specialization
    // argument was given)
    if (    target->IsA(Target::RECORD)
         && Cast<TGTRecord,NC>(target)->SpecializationArgs
         && (addTArgs || SpecializationArgs ) )
        Cast<TGTRecord,NC>(target)->SpecializationArgs->Print(newDisplay);
 
    // add variable subscript? (done when something matching was given)
    if (    target->IsA(Target::Variable)
         && (addSubscript || Subscript.IsNotNull())  )
        newDisplay << Cast<TGTVariable,NC>(target)->Subscript;
 
    // add file path to #define?
    if (addParents && target->IsA(Target::Macro)) {
        newDisplay._<NC>(" (");
        auto parent= node;
        int cntParentOverflow = 0;
        for (; cntParentOverflow < addParents && !parent.IsRoot(); ++cntParentOverflow)
            parent= parent.Parent();
        if ( parent.IsRoot() && cntParentOverflow < addParents)
            Error= XLink::Errors::TooManyParentsRequested;
        ALIB_LOCK_SHARED_WITH(node.Index().SLock)
        node.Parent().Path(newDisplay, parent);
        newDisplay._<NC>(") ");
    }
 
    // finally, add what the user added to the display
    if ( display.IsNotEmpty() )
        newDisplay << display;
    ConvertASCIItoHTMLEntities(newDisplay);
    Display   = String(MA, newDisplay);
}
 
 
#if defined(TODO_IS_NEEDED_AGAIN)
namespace {
//todo: Hier gehts weiter:
//X erstmal alle fehler im ALib nun noch korrigieren
//- dann die neuen Maps
//  - per filename
//  - per anchor aufbauen.
//- dann das Resolving umstellen auf den echten parent, den man aus dem filenamen direkt nachschlägt
//- Achso: Statt den filenamen zu speichern, kann man auch den Tree-node direkt im Tag-file ablegen.
//  - Das geht natürlich nur mit dem Haupt-Tagfile, also dem letzten in Indices.
//  - Dem Index also ein Flag "IsMainTagFile" geben und dem HTML-Base in den Targets eine union
//    machen: Entweder String oder exported File cursor.
//  - Dazu also als allererstes den HTML-Tree parsen, ohne notify und Job-Start. Dies trennen.
//    (oder war es da getrennt, naja, siehst du ja dann) und im Tag-file den Node suchen.
//  - Im Index::Search dann, bei ein local links sofort aufhören, wenn nicht IsMainTagFile.
//  - Dann im DXL ein feature einfügen, welches auf die Möglichkeit hinweist, dass ein Link
//    zum Local-Link gemacht werden kann. Leider kommen dann falsche source-locations heraus.
//    Da muss man am Anfang der Liste einen hübschen Erklärungstext hinzufügen.
 
    // Converts a doxygen file name (mangled) back to the entity that the file documents
    int parseFileScope( files::File htmlFile, String* fileScope,
                        MonoAllocator& ma, int MAX_SCOPE_DEPTH ) {
        String256 fileName(htmlFile.Name());
 
        // first parse the known entity types
        integer scopeStart =   fileName.StartsWith("struct")      ? 6
                             : fileName.StartsWith("class")       ? 5
                             : fileName.StartsWith("union")       ? 5
                             : fileName.StartsWith("namespace")   ? 9
                             : fileName.StartsWith("concept")     ? 7
                             : -1;
        if ( scopeStart < 0)
            return 0;
        fileName.ShortenTo( fileName.LastIndexOf('.') );
 
        // replace mangled characters
        fileName.DeleteStart(scopeStart);
        fileName.SearchAndReplace( "_8"  , "@" );
        fileName.SearchAndReplace( "_1_1", "@" );
        fileName.SearchAndReplace( "__"  , "_" );
 
        // parse the scope that the filename represents
        Substring parser(fileName);
        int scopeSize= 0;
        while (parser.IsNotEmpty() && scopeSize < MAX_SCOPE_DEPTH )
            fileScope[scopeSize++]= String( ma, parser.ConsumeToken('@') );
        return scopeSize;
    }
}
#endif //defined(TODO_IS_NEEDED_AGAIN)
 
std::pair<XLink*,bool>  XLink::GetLocalCopy(const File& htmlFile) {
    // first check if a local link exists already for this file
    auto htmlFileHandle= htmlFile.AsCursor().Export();
    XLink* xl= this;
    while (xl) {
        if (xl->HTMLFileOfLocalLink == htmlFileHandle)
            return std::make_pair(xl, false);
        xl= xl->NextLocal;
    }
 
    // now either choose us (if we're still empty) or create a new one
    if (HTMLFileOfLocalLink != 0) { //already used
        auto* oldNext= NextLocal;
        NextLocal= MA().New<XLink>(); ALIB_DBG(NextLocal->MA.DbgCriticalSectionsPH.Construct(nullptr));
        NextLocal->LinkString= LinkString;
        NextLocal->Parse();
        NextLocal->NextLocal= oldNext;
        xl= NextLocal;
    } else
        xl= this;
 
    ALIB_ASSERT(    xl->IsLocal
                &&  xl->IsParsed()
                &&  xl->Error <= Errors::WARNINGMARKER
                &&  xl->scopeHintsSize == 0                     , "DXL/XLINK")
 
    // store the file.
    xl->HTMLFileOfLocalLink= htmlFileHandle;
    return std::make_pair(xl, true);
}
 
void XLink::PrintError(Paragraphs& out, const String& linkString, bool suppressHints) {
 
    //---------------- lamda function that assembles the name of a target ----------------
    auto printType= [&](const String& headLine, const Index::Node& targetNode, bool withPath) {
        String512 np;
        String32 kindName;
        const Target* target= targetNode.Target();
 
        // resolve kind name
        if ( auto* rec= Cast<TGTRecord>(target);
             rec && rec->TemplateArgs )
            np._("template ");
 
        bool isMember     =      targetNode.Parent()!=targetNode.Index().Root()
                             && !targetNode.Parent().IsA(Target::Namespace);
        bool isConstructor=      isMember
                             &&  targetNode.Parent().Name().Equals(Name());
        if (target->IsA(Target::Function))
            kindName= !isMember       ? "namespace-function"
                      : isConstructor ? "constructor"
                      :                 "member-function";
        else if (target->IsA(Target::Variable))
            kindName= isMember ? "member-variable" : "namespace-variable";
        else if ( auto* rec= Cast<TGTRecord>(target);
                  rec && rec->SpecializationArgs )
            kindName= "specialization";
        else if ( auto* macro= Cast<TGTMacro>(target); macro )
            kindName= macro->Args ? "preprocessor macro"
                                  : "preprocessor constant";
        else kindName= target->Kind();
 
        // Add type code
        char typeCode= 0;
             if (target->IsA(Target::Dir         )) typeCode= 'D';
        else if (target->IsA(Target::File        )) typeCode= 'F';
        else if (target->IsA(Target::Macro       )) typeCode= 'P';
        else if (target->IsA(Target::Namespace   )) typeCode= 'N';
        else if (target->IsA(Target::Concept     )) typeCode= 'O';
        else if (target->IsA(Target::Typedef     )) typeCode= 'T';
        else if (target->IsA(Target::Class       )) typeCode= 'C';
        else if (target->IsA(Target::Struct      )) typeCode= 'S';
        else if (target->IsA(Target::Union       )) typeCode= 'U';
        else if (target->IsA(Target::Enumeration )) typeCode= 'E';
        else if (target->IsA(Target::EnumElement )) typeCode= 'A';
        else if (target->IsA(Target::Function    )) typeCode= 'M';
        else if (target->IsA(Target::Variable    )) typeCode= 'V';
        if( typeCode) np._("(")._(typeCode)._(") ");
 
        np._(kindName).InsertChars(' ', 10-np.Length())._<NC>(' ');
 
        // resolve name
        if (auto* rec= Cast<TGTRecord>(target);
            rec && rec->TemplateArgs           ) {
                np._("template ");
                rec->TemplateArgs->Print(np);
                np._(' ');
        }
        if (withPath && !target->IsA(Target::Macro) && !targetNode.Parent().IsRoot()) {
            String512 pathBuf;
            {ALIB_LOCK_SHARED_WITH(targetNode.Index().SLock)
            targetNode.Parent().Path(pathBuf); }
            np._(pathBuf)._<NC>("::");
        }
 
        String name=  targetNode.Name();
        if ( target->IsA(Target::RECORD)) {
            integer templatePos= name.IndexOfOrLength('<');
            ALIB_DBG(assert(name.IndexOf('(')<0));
            name= name.Substring(0, templatePos);
        }
        np._(name);
 
        if (auto* rec= Cast<TGTRecord>(target);  rec && rec->SpecializationArgs )
            rec->SpecializationArgs->Print(np);
 
        if (auto* var= Cast<TGTVariable>(target); var)
            np << var->Subscript;
 
        if (auto* macro= Cast<TGTMacro>(target); macro && macro->Args)
            macro->Args->Print(np);
 
        String256 link(targetNode.Index().BaseURL);
        link << '/' << target->HTMLFile;
        if (auto* mem= Cast<TGTMember>(target); mem)
            link << '#' << mem->Anchor;
 
        if (withPath && target->IsA(Target::Macro)) {
            String512 pathBuf;
            targetNode.Parent().Path(pathBuf);
            np._<NC>(" in file: ")._<NC>(pathBuf);
        }
 
        //out.
        integer oldLineWidth= out.LineWidth;
        out.LineWidth= 0;
        out.Add("{} {} {!ATab} {}:{} {!ATab} {} "
                , headLine
                , np
                , "tag: "
                , targetNode.Index().FilePath
                , target->LineNo
                , "->: "
                , link
        );
        out.LineWidth= oldLineWidth;
    }; // inner function 'printType'
 
 
    //---------------- Error in XLink? ----------------
    if ( Error != Errors::OK ) {
        out.Add("XLink #{!Q} {}:", linkString, Error > Errors::WARNINGMARKER ? "is erroneous"
                                                                             : "has a warning" );
        out.PushIndent(2);
            out.Add(APPCLI_CAMP.GetResource(String64("XL_ERR_")._(int(Error))) );
        out.PopIndent();
        return;
    }
 
 
    //---------------- indirection and not ^ and vice versa ----------------
    if ( Targets.size() == 1 ) {
 
        if (    NoIndirectionWarning
            && !Result().IsIndirectByInheritance
            && !Result().IsIndirectByTypeDef
            && !Result().IsIndirectLinkToScannedHTMLSourceFile ) {
            out.Add("Warning: XLink #{!Q} uses indirection prefix '^', while it targets a "
                             "direct member in the parent scope.\n"
                    "  Hint: Remove the prefix from the XLink", linkString );
            printType("  Target:", Result().Node, true);
            return;
        }
 
        if (    !NoIndirectionWarning
             && (    Result().IsIndirectByInheritance
                  || Result().IsIndirectByTypeDef
                  || Result().IsIndirectLinkToScannedHTMLSourceFile    )  ) {
            out.Add("Warning: XLink #{!Q} has an indirect target but is not marked with the "
                             "indirection prefix '^'.",
                    linkString );
            printType("  Target:", Result().Node, true);
            return;
        }
 
        if (    !NoIndirectionWarning
             && Result().IsIndirectLinkToScannedHTMLSourceFile ) {
            out.Add("Warning: XLink #{!Q} links to an HTML-file found in the output folder "
                    "(not the tag file)!\n"
                    "Mark this link with indirection prefix '^' (to silence this warning).",
                    linkString );
            printType("  Target:", Result().Node, true);
            return;
        }
 
        ALIB_ASSERT_WARNING(Error != Errors::OK, "DXL/XLINK",
             "No error to print for this valid XLink \"{}\" in the sources", linkString )
        return;
    }
 
    //---------------- remove from same-name-list if found in a more concrete list ----------------
 
    std::erase_if(DidYouMeanSameName, [&](const auto& it) {
        // remove if duplicate
        for (auto& target : Targets)
            if (target.Node == it)
                return true;
 
        // remove from other lists
        if ( it == DidYouMeanTemplateType
            || std::find( DidYouMeanFunctionOverload.begin(), DidYouMeanFunctionOverload.end(), it )
                       != DidYouMeanFunctionOverload.end()
            || std::find( DidYouMeanVariable        .begin(), DidYouMeanVariable        .end(), it )
                       != DidYouMeanVariable        .end()
            || std::find( DidYouMeanNotATemplate    .begin(), DidYouMeanNotATemplate    .end(), it )
                       != DidYouMeanNotATemplate    .end()
            || (    ScopeSize()
                &&  linkToParentScope
                &&  linkToParentScope->BaseTypes
                && std::find_if( linkToParentScope->Targets.begin(), linkToParentScope->Targets.end(),
                                [it]( Index::SearchResult& result) { return it==result.Node; })
                               != linkToParentScope->Targets.end()                                  )
            || (    ScopeSize()
                &&  linkToParentScope
                &&  linkToParentScope->TypeDefinitionTargets
                && std::find( linkToParentScope->TypeDefinitionTargets->begin(), linkToParentScope->TypeDefinitionTargets->end(), it )
                           != linkToParentScope->TypeDefinitionTargets->end()                          )
            ) return true;
 
        return false;
    });
 
 
    //---------------- ambiguous? ----------------
    if ( Targets.size() > 1 ) {
        out.Add("Ambiguous XLink #{!Q}.", linkString);
        if (suppressHints)
            return;
        out.PushIndent(2);
            for (auto& target : Targets)
                printType("Could be", target.Node, true);
 
            // Template type?
            if (DidYouMeanTemplateType.IsValid())
                printType("Could be", DidYouMeanTemplateType, true);
 
            // Variable with different subscript
            for ( auto& variable : DidYouMeanVariable )
                printType("Could be", variable, true);
 
            // Loop over list of nodes with the same name
            if (DidYouMeanSameName.size()) {
                out.Add("Further entities with the same name:");
                out.PushIndent(2);
                for (auto& node : DidYouMeanSameName )
                    printType( "", node, true);
                out.PopIndent();
            }
        out.PopIndent();
        return;
    }
 
    //---------------- not found! (Target.size()==0) ----------------
    out.Add("Unresolved XLink #{!Q}.", linkString);
    if (suppressHints)
        return;
 
    out.PushIndent(2);
    LocalAllocator2K la;
    HashSet<MonoAllocator, const Target*> nodesListed(la);
    
 
    // If a parent-path was given
    if (ScopeSize()>0) {
        ALIB_DBG(MA.DbgCriticalSectionsPH->DCSLock= nullptr;)
        if (!GetLinkToParent()->Targets.size()) {
            out.Buffer << ("  Given parent scope \"");
            for ( int i= 0; i< HintsSize(); ++i)
                out.Buffer << Hint(i)  << ' ';
            for ( int i= 0; i< ScopeSize(); ++i)
                out.Buffer << Scope(i) << (HasOneOf(KindSpec, Target::Dir | Target::File)
                                                 ? String8(system::DIRECTORY_SEPARATOR) : "::"  );
            out.Buffer << ("\" not found.\n");
        }
 
        // If parent-path was found, list possible parents' children
        else {
            out.Add( "Collecting proposals of compound type(s) and base types: ");
            out.PushIndent(2);
 
            // collect all nodes in one vector
            std::vector<Index::Node> parents;
            parents.reserve(  linkToParentScope->Targets.size()
                            + ( BaseTypes            ? size_t(BaseTypes->size())             : 0 )
                            + ( TypeDefinitionTargets? size_t(TypeDefinitionTargets->size()) : 0 ) );
 
            for (auto& target : linkToParentScope->Targets)
                parents.push_back(target.Node);
            if (BaseTypes)
                for (auto& target : *BaseTypes)
                    parents.push_back(target);
            if (TypeDefinitionTargets)
                for (auto& target : *TypeDefinitionTargets)
                    parents.push_back(target);
 
            bool foundSimilar= false;
            for (int phase=0 ; phase<5 ; ++phase) {
                for (auto& didYouMeanChildOf : parents) {
                    if ( didYouMeanChildOf.IsA(Target::FILEPATH_COMPONENT) )
                        continue;
                    out.PushIndent(2);
 
                    // first search vice-versa start-strings
                    if ( phase != 4) {
                        String searchedName= Name();
                        auto child= didYouMeanChildOf.AsCursor().FirstChild();
                        while ( child.IsValid() ) {
                        bool hits=
                           ( phase == 0 // vice-versa start strings, case sensitive
                              && (    child.Name().StartsWith<CHK,lang::Case::Sensitive>(searchedName)
                                   || searchedName.StartsWith<CHK,lang::Case::Sensitive>(child.Name()) ) )
                         ||( phase == 1 // vice-versa start strings, case ignore
                              && (    child.Name().StartsWith<CHK,lang::Case::Ignore   >(searchedName)
                                   || searchedName.StartsWith<CHK,lang::Case::Ignore   >(child.Name()) ) )
                         ||( phase == 2 // vice-versa substrings, case sensitive
                              && (    child.Name().IndexOf   <NC,lang::Case::Sensitive>(searchedName) >=0
                                   || searchedName.IndexOf   <NC,lang::Case::Sensitive>(child.Name()) >=0 ) )
                         ||( phase == 3 // vice-versa substrings, case ignore
                              && (    child.Name().IndexOf   <NC,lang::Case::Ignore   >(searchedName) >=0
                                   || searchedName.IndexOf   <NC,lang::Case::Ignore   >(child.Name()) >=0 ) )
                            ;
 
                            if (hits && nodesListed.InsertIfNotExistent(child.Value()).second) {
                                if (!foundSimilar) {
                                    printType("Did you mean an entity in", didYouMeanChildOf, true);
                                    foundSimilar= true;
                                }
                                printType("  ", child, false);
                            }
                            child.GoToNextSibling();
                        }
                    }
 
                    // finally, if still none was found, just dump some
                    else if ( !foundSimilar) {
                        auto child= didYouMeanChildOf.AsCursor().FirstChild();
                        while (child.IsValid()) {
                            if ( nodesListed.InsertIfNotExistent(child.Value()).second) {
                                if (!foundSimilar) {
                                    printType("Did you mean an entity in", didYouMeanChildOf, true);
                                    foundSimilar= true;
                                }
                                printType("  ", child, false);
                            }
                            child.GoToNextSibling();
                        }
                    }
                    out.PopIndent();
                }
            }
            out.PopIndent();
        } // possible parents found
    } // parent path was given
 
    // Template type?
    if (   DidYouMeanTemplateType.IsValid()
        && nodesListed.InsertIfNotExistent(DidYouMeanTemplateType.Target()).second ) {
        printType("You probably meant:", DidYouMeanTemplateType, true);
        out.PushIndent(2);
        // Loop over the list of nodes with the same name (specializatios)
        for (auto& indexCursor : DidYouMeanSameName )
            printType("Or ", indexCursor, true);
        out.PopIndent();
        out.PopIndent();
        return;
    }
 
    // Loop over the list of overloaded functions
    for (auto& indexCursor : DidYouMeanFunctionOverload ) {
        if ( nodesListed.InsertIfNotExistent(indexCursor.Target()).second )
            printType(indexCursor.IsA(Target::Macro) ? "Did you mean"
                                                               : "Did you mean overloaded",
                      indexCursor, true);
    }
 
    // Loop over the list of overloaded functions
    for (auto& indexCursor : DidYouMeanVariable )
        if ( nodesListed.InsertIfNotExistent(indexCursor.Target()).second )
            printType("Subscript mismatch with: ", indexCursor, true);
 
    // Loop over the list of nodes with the same name
    for (auto& indexCursor : DidYouMeanSameName )
        if ( nodesListed.InsertIfNotExistent(indexCursor.Target()).second )
            printType("Did you mean", indexCursor, true);
 
 
    out.PopIndent();
}
 
} //namespace [dxl]