tagfile.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 "index.hpp"
#include "dxl.hpp"
#include "dxlapp.hpp"
#include "ALib.ALox.H"
#include "ALib.Strings.StdIOStream.H"
#include "ALib.Containers.StringTreeIterator.H"
#include "ALib.App.H"
 
 
using namespace alib;
using namespace std;
 
namespace dxl {
 
Index::Parser::Parser(Index& parent, alib::IStreamReader& pReader, const alib::String& pFilePath)
: index        {parent}
, dxl          {*alib::app::Get<DXLApp>().dxl}
, ma           {parent.ma}
, reader       {pReader}
, FilePath     {pFilePath}
, actDocAnchors{ma}                                                                   {}
 
 
void Index::Parser::nextLine() {
    START:
    reader.Read(lineBuf);
    ConvertHTMLEntitiesToAscii(lineBuf);
    line= lineBuf;
    line.TrimStart();
    ++lineNo;
    maxWidth= std::max(maxWidth, lineBuf.Length());
 
    // <docanchor> might appear anywhere. That's why we handle them here.
    if (line.StartsWith("<docanchor")){
        String name         = allocTag("docanchor");
        String256 anchorFile= parseAttr("file");
        String256 title     = parseAttr("title", true);
 
        // remove escape chars '\'
        // Note: Since doxygen Version 1.16 we had to insert the backslash to the title, because
        //       otherwise the TOC did not work. (Strange new doxygen bug we think)
        integer pos= 0;
        for (;;) {
            pos= title.IndexOf('\\', pos);
            if (pos<0)
                break;
            title.Delete(pos,1);
            pos++;
        }
        String titleStr(ma, title);
        actDocAnchors.push_back(ma().New<TGTDocAnchor>( String(ma, anchorFile ),
                                                        lineNo, name, titleStr));
        goto START;
    }
}
 
void  Index::Parser::addDocAnchors(Cursor& parent) {
    for (auto* actDocAnchor: actDocAnchors) {
        if ( !parent.Value()->HTMLFile.Equals(actDocAnchor->HTMLFile) )  {
            if (verbosity >= Verbosity::Info) {
                Lox_Info("Skipping anchor {!Q} in compound {!Q} of type {}, because it has a\n"
                         "different HTML file-target than its parent.\n"
                            "   Compound target:   {}\n"
                            "   DocAnchor Target:  {}\n"
                            "   In tag-file:       @ {}:{}\n"
                            ,actDocAnchor->Name, parent.Name(), parent.Value()->Kind()
                            ,parent.Value()->HTMLFile
                            ,actDocAnchor  ->HTMLFile
                            ,FilePath, actDocAnchor->LineNo + 1)
            }
            continue;
        }
 
        Cursor newChild= parent.CreateChild(actDocAnchor->Name, actDocAnchor);
        if ( newChild.IsInvalid() ) {
            String256 path;
            parent.AssemblePath(path);
            Cursor previous= parent.Child(actDocAnchor->Name);
            Lox_Error( "Doubly defined anchor {!Q} in compound {!Q} of type {} (ignoring)\n"
                       "   First definition  @ {}:{}\n"
                       "   Second definition @ {3}:{}"
                       ,actDocAnchor->Name, parent.Name(), parent.Value()->Kind()
                       ,FilePath
                       ,previous.Value()->LineNo, actDocAnchor->LineNo )
        }
 
    }
    actDocAnchors.Clear();
}
 
String Index::Parser::parseTag(const String& tagName) {
    tagAttr= nullptr;
    if (!line.ConsumeChar('<') )
        throw Exception(ALIB_CALLER_NULLED, Exceptions::NotATagStart, FilePath,lineNo, line);
    if (!line.StartsWith(tagName))
        throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag, FilePath,lineNo, tagName, line);
 
    line.ConsumeChars(tagName.Length());
 
    // attributes following?
    integer attrEnd= 1;
    if ( line.CharAtStart() == ' ' ) {
        // find next '>' which is not in a string.
        bool inString= false;
        for (; attrEnd<line.Length(); ++attrEnd) {
            character c= line.CharAt<NC>(attrEnd);
            if (c == '\"' && line.CharAt<NC>(attrEnd - 1) != '\\') {
                inString= !inString;
                continue;
            }
            if (!inString && c == '>' )
                break;
        }
        if ( attrEnd == line.Length())
            throw Exception(ALIB_CALLER_NULLED, Exceptions::XMLSyntaxError, FilePath,lineNo, tagName, line);
        tagAttr= line.Substring(1, attrEnd-1);
        line.ConsumeChars<NC>(attrEnd + 1 );
        if (line.IsEmpty())
            return line;
    }
    else {
        if (line.CharAtStart() != '>')
            throw Exception(ALIB_CALLER_NULLED, Exceptions::XMLSyntaxError, FilePath,lineNo, tagName, line);
        line.ConsumeChar();
        tagAttr= EMPTY_STRING;
    }
 
     if (line.EndsWith(String64("</")._<NC>(tagName)._<NC>('>')) )
        return line.Substring(0, line.Length()- (tagName.Length() + 3));
 
    if (!line.EndsWith(">"))
        throw Exception(ALIB_CALLER_NULLED, Exceptions::XMLSyntaxError, FilePath,lineNo, lineBuf);
 
    line.ConsumeCharsFromEnd(1);
    return line;
 
}
 
String Index::Parser::parseAttr(const String& attrName, bool isOptional) {
    integer idxStart= 0;
    for (;;) {
        idxStart= tagAttr.IndexOf(attrName, idxStart);
        if ( idxStart<0 ) {
            if ( !isOptional )
                Lox_Error("Unexpected Doxygen tag-file format: Missing attribute {!Q}\n"
                          "   Line read:  {}\n"
                          "   @ {}:{}\n"
                          ,attrName
                          ,line
                          ,FilePath, lineNo)
            return nullptr;
        }
        if (    tagAttr.CharAt(idxStart + attrName.Length()    ) == '='
             && tagAttr.CharAt(idxStart + attrName.Length() + 1) == '\"' )
            break;
        idxStart+= attrName.Length() + 1;
    }
    idxStart+= attrName.Length() + 2;
    bool escaped= false;
    integer idxEnd= idxStart;
    for (; idxEnd<tagAttr.Length(); ++idxEnd) {
        character c= tagAttr.CharAt<NC>(idxEnd);
        if (!escaped) {
            if (c == '"')
                break;
            if ( c == '\\' )
                escaped= true;
        }
        else
            escaped= false;
    }
    if ( idxEnd == tagAttr.Length() )
        throw Exception(ALIB_CALLER_NULLED, Exceptions::XMLSyntaxError,
                        FilePath, lineNo, line);
 
    return tagAttr.Substring( idxStart, idxEnd-idxStart);
}
 
/// todo: add parameter parent and if html file is the same, then re-use instead of allocation.
TGTMember* Index::Parser::readMember(String512& key, Target::Kinds compoundType) {
    if (!line.ConsumeString( "<member kind=\"" ))
        throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                        FilePath, lineNo, "member", line);
    Target::Kinds kind;
    if (! enumrecords::Parse(line, kind) )
        throw Exception(ALIB_CALLER_NULLED, Exceptions::UnknownKind, FilePath, lineNo, line);
 
    // parse a refID: todo: I have no samples, yet for this. Not tested!
    String128 refID;
    line.ConsumeChar('"');
    line.TrimStart();
    if (line.ConsumeString("refid=\"")) {
        refID = line.ConsumeToken('"');
    }
 
    key.Reset();
 
    // pre-processor defines
 
    if ( kind == Target::Macro ) {
        int lNo= lineNo;
        ALIB_DBG(String type=)
        nextTag("type");
        ALIB_ASSERT_ERROR(type.Equals("#define"), "DXL/TAGFILE", "Expected '#define' as type")
        key               << nextTag("name");
        auto* member      = ma().New<TGTMacro>(allocNextTag("anchorfile"), lNo);
        member->Anchor    = allocNextTag("anchor");
        Substring argList = nextTag("arglist");
        member->Args      = Target::FunctionArguments::PARSE(ma, argList);
        nextLine();
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // typedef
    if ( kind == Target::Typedef ) {
        int lNo= lineNo;
        String type   = allocNextTag("type");
        key          << nextTag("name");
 
        TGTTypedef* member= ma().New<TGTTypedef>(allocNextTag("anchorfile"), lNo);
        member->Type  = type;
        member->Anchor= allocNextTag("anchor");
        if ( nextTag("arglist").IsNotEmpty() )
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLValue, FilePath,lineNo, "arglist should be empty", lineBuf);
        nextLine();
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // typedef or enumeration
    if ( kind == Target::Enumeration ) {
 
        int lNo= lineNo;
        String type   = allocNextTag("type");
        key          << nextTag("name");
 
        TGTEnumeration* member= ma().New<TGTEnumeration>(allocNextTag("anchorfile"), lNo);
        member->Type  = type;
        member->Anchor= allocNextTag("anchor");
        if ( nextTag("arglist").IsNotEmpty() )
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLValue, FilePath,lineNo, "arglist should be empty", lineBuf);
        nextLine();
        if (line.StartsWith("<enumvalue")) {
            // the caller has to check whether line is "<enumvalue..." and add each value as its child.
            return member;
        }
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // enum value
    if ( kind == Target::EnumElement ) {
        int lNo= lineNo;
        key             << nextTag("name");
        TGTEnumValue* member= ma().New<TGTEnumValue>(allocNextTag("anchorfile"), lNo);
        member->Anchor  = allocNextTag("anchor");
        if ( nextTag("arglist").IsNotEmpty() )
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLValue, FilePath,lineNo, "arglist should be empty", lineBuf);
 
        nextLine();
        if (!line.StartsWith("</member")) {
            if ( kind != Target::Enumeration )
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag, FilePath,lineNo, "/member", line);
 
            // the caller has to check whether line is "<enumvalue..." and add each value as its child.
            return member;
        }
 
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // variables
    if ( kind == Target::Variable ) {
        int lNo= lineNo;
        String1K argList;
        String type= allocNextTag("type");
        key             << nextTag("name");
        TGTVariable* member= ma().New<TGTVariable>(allocNextTag("anchorfile"), lNo);
        member->Type     = type;
        member->Anchor   = allocNextTag("anchor");
        member->Subscript= allocNextTag("arglist");
 
        nextLine();
        if (!line.Equals("</member>"))
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag, FilePath,lineNo, "/member", line);
 
        // checks on variables
        if ( argList.IsNotEmpty() && argList.CharAtStart()!='[' )
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLValue, FilePath,lineNo, "arglist starting with '['", argList);
        if (!line.Equals("</member>"))
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag, FilePath,lineNo, "/member", line);
 
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // functions
    if ( kind == Target::Function ) {
        int lNo= lineNo;
        String type= allocNextTag("type");
        key             << nextTag("name");
        TGTFunction* member= ma().New<TGTFunction>(allocNextTag("anchorfile"), lNo);
        member->Type= type;
        member->Anchor= allocNextTag("anchor");
 
        Substring argList= nextTag("arglist");
        if ( argList.IsNotEmpty() && !argList.Equals("()") ) {
            if (argList.CharAtStart() != '(' )
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLValue, FilePath,lineNo,
                                "arglist starting with '('", argList);
            member->Args= Target::FunctionArguments::PARSE(ma, argList);
            if (member->Args == nullptr)
                throw Exception(ALIB_CALLER_NULLED, Exceptions::XMLSyntaxError,
                                FilePath, lineNo, line);
            member->Args->Print(key);
            if (argList.Trim().IsNotEmpty())
                member->Qualifiers= String(ma, argList);
        }
        
        if ( member->Qualifiers.IsNotEmpty() )
            key << ' ' << member->Qualifiers;
 
        nextLine();
        if (!line.Equals("</member>"))
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag, FilePath,lineNo,
                            "/member", line);
        if (refID.IsNotEmpty())
            member->RefID= String(ma, refID);
        return member;
    }
 
    // warn if not a group-member (and not fetched above)
    if (compoundType != Target::Group  &&  verbosity >= Verbosity::Warning)
        Lox_Warning("Unexpected member type {} in compound of type {}. Ignoring.",
                    kind, compoundType)
 
    // read generic (group) members
    TGTGenericMember* member= ma().New<TGTGenericMember>(kind, alib::NULL_STRING, lineNo);
    if (refID.IsNotEmpty())
        member->RefID= String(ma, refID);
    for (;;) {
        nextLine();
        if (line.Equals("</member>"))
            break;
             if (line.StartsWith("<name"))       key             << nextTag("name");
        else if (line.StartsWith("<anchorfile")) member->HTMLFile= allocNextTag("anchorfile");
        else if (line.StartsWith("<anchor"))     member->Anchor  = allocTag("anchor");
    }
    if (key.IsNotEmpty())
        return member;
 
    Lox_Warning("Unnamed (generic) member of type {} in compound of type {}. Ignoring.",
                 member->Kind, compoundType)
    return nullptr;
}
 
 
void  Index::loadTagFile() {
    Lox_SetDomain("DXL/TAGFILE", Scope::Filename )
    Lox_Info("Reading tag-file: ", FilePath )
    static TGTFilePathComponent filePathComponentTag(-1);
 
    errno= 0;
    std::ifstream ifstream;
    ifstream.open( Path(FilePath).Terminate() );
 
    DXLApp&         app= app::Get<DXLApp>();
    if ( !ifstream.is_open() || errno ) {
        app.cErr->Add(app.cli.ExitCodeDecls.Find(ExitCodes::TagFileNotFound).Mapped()->FormatString(),
                      FilePath, app.DoxyfilePath);
        app.machine.SetExitCode(ExitCodes::TagFileNotFound);
        throw Exception( ALIB_CALLER_NULLED, app::App::Exceptions::ControlledEarlyExit );
    }
 
    IStreamReader reader(1024,1024);
    reader.SetStream( &ifstream );
 
    ALIB_ALLOW_MISSING_FIELD_INITIALIZERS
    Parser parser(*this, reader, FilePath);
    ALIB_POP_ALLOWANCE
    // we want maximum speed and even spare the fast log calls in the loop.
    Lox_GetVerbosity(parser.verbosity)
 
    // skip 1st line
    parser.nextLine();
    ALIB_ASSERT_ERROR(parser.line.StartsWith("<?xml version='1.0'"), "DXL/TAGFILE", "Unknown file format")
 
    // print doxygen version
    parser.nextTag("tagfile");
    Lox_Info("Doxygen version: ", parser.getAttr("doxygen_version") )
    while( !reader.IsEOF() ) {
        // read line
        parser.nextLine();
 
        if (parser.line.Equals("</tagfile>"))
            break;
 
        // not a compound?
        if ( parser.tryTag("compound").IsNull() ) {
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                            FilePath, parser.lineNo, "compound", parser.line);
        }
 
        //========== new compound ==========
        Target::Kinds kind;
        Substring kindStr= parser.getAttr("kind");
        if (! enumrecords::Parse( kindStr, kind ) )
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnknownKind,
                            FilePath, parser.lineNo, parser.lineBuf );
 
        //Lox_Warning("{}  @ {}:{}", kind, filePath, lineNo)
 
        //--------------------------  Compound struct/class/union  ---------------------------------
        if ( kind & Target::COMPOUND )  {
            String1K compoundTagName  = parser.nextTag("name");
            String compoundHtmlFile= parser.allocNextTag("filename");
 
            // local collection of template args given with tag <templarg>.
            // Will be added on finalization to TGT
            LocalAllocator2K la;
            String* templateArgs= la().NewArray<String>(Target::MAX_TEMPLATE_ARGS);
            int templateArgsSize= 0;
 
 
            // cut off template specialization args"<..." from name.
            Substring compoundNameWithoutTemplateParams= compoundTagName;
            Substring templateSpecializationArgs= nullptr;
            if ( compoundTagName.CharAtEnd<NC>() == '>') {
                integer templateStart= compoundTagName.IndexOf('<');
                ALIB_ASSERT(templateStart>0, "DXL/TAGFILE")
                compoundNameWithoutTemplateParams= compoundTagName.Substring(0, templateStart);
                compoundNameWithoutTemplateParams.TrimEnd();
                templateSpecializationArgs       = compoundTagName.Substring(templateStart);
                templateSpecializationArgs       .TrimStart();
            }
 
            // extract the path to the component by finding the last "::"
            String  compoundPathPortion= nullptr;
            integer lastPathPos= compoundNameWithoutTemplateParams.LastIndexOf(':');
            if ( lastPathPos>=0 ) {
                ALIB_ASSERT_ERROR(compoundTagName.CharAt(lastPathPos -1) == ':', "DXL/TAGFILE",
                   "Single colon ':' found in compound name {!Q}", compoundTagName )
                compoundPathPortion= compoundTagName.Substring(0, lastPathPos -1);
                compoundNameWithoutTemplateParams= compoundNameWithoutTemplateParams.Substring(lastPathPos + 1);
            }
 
            // create the path to the new component.
            Cursor    pathCursor    = Root();
            if ( compoundPathPortion.IsNotEmpty() ) {
                Tokenizer tok(compoundPathPortion, ':');
                while (tok.HasNext()) {
                    String pathComponent= tok.Next();
                    Cursor component= pathCursor.CreateChild(pathComponent, nullptr);
                    // If it did not exist, we create an unknown component. A compound will
                    // hopefully replace this later. This may happen because "deeper" compounds
                    // can come first in doxygen tag-files.
                    if ( component.IsValid()) {
                        component.Value()= ma().New<TGTFilePathComponent>(parser.lineNo);
                        pathCursor= component;
                    }
                    else
                        pathCursor.GoToChild(tok.Actual);
 
                    // skip the next ':'
                    tok.Next();
                }
            }
 
            // Now create the child itself. Template parameters have to be included in the key.
            String compoundKey= compoundPathPortion.IsNotEmpty()
                                ? compoundTagName.Substring(compoundPathPortion.Length() + 2)
                                : compoundTagName;
            Cursor compoundCursor= pathCursor.CreateChild(compoundKey, nullptr);
            if ( compoundCursor.IsInvalid()) {
                compoundCursor= pathCursor.Child(compoundKey);
 
                if (!compoundCursor.Value()->IsA(Target::UNKNOWN_COMPOUND | Target::FILEPATH_COMPONENT))
                    throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                    compoundKey, compoundPathPortion, FilePath,
                                    pathCursor.Child(compoundKey).Value()->LineNo, parser.lineNo);
            }    
 
            // Add Namespace or Struct/Class/Union tag
            TGTNamespace* tagNamespace= nullptr;
            TGTRecord*    tagRecord=    nullptr;
            if ( kind == Target::Namespace) {
                compoundCursor.Value()=
                tagNamespace= ma().New<TGTNamespace>(compoundHtmlFile, parser.lineNo);
                ALIB_ASSERT(templateSpecializationArgs.IsNull(), "DXL/TAGFILE")
            }
            else {
                compoundCursor.Value()=
                tagRecord= ma().New<TGTRecord>(ma, kind, compoundHtmlFile, parser.lineNo);
                // Todo:
                // The name is internally allocated, hence the template args could be just stored.
                // We could do the same on the XLink-side by allocating the string to parse.
                // This would spare us the allocation.
                // Also: both types, TemplateArguments and FunctionArguments should use a
                // forward list.
                // but it is ok as it is...
                if ( templateSpecializationArgs.IsNotEmpty())
                    tagRecord->SpecializationArgs= Target::TemplateArguments::PARSE(ma, templateSpecializationArgs);
            }
 
 
            //-----------------  read members ---------------
            for(;;) {
                parser.nextLine();
                parser.addDocAnchors(compoundCursor);
 
                if ( parser.line.StartsWith("<member kind=") ) {
                    String512 key;
                    TGTMember* member= parser.readMember(key, kind);
                    if (!member) continue;
                    //Dump(compoundCursor);
                    Cursor memberChild= compoundCursor.CreateChild(key, member);
                    if ( memberChild.IsInvalid() ) {
                        Target* existingValue= compoundCursor.Child(key).Value();
                        if ( member->IsA(Target::Function) ) {
                            // this is just strange: sometimes doxygen adds the very same
                            // member twice. We just ignore that.
                            // However, if just the anchor is different, then either DXL is
                            // wrong or a newer doxygen version does something different.
                            // Thus we throw.
                            if (    !existingValue->IsA(Target::Function)
                                 && !Cast<TGTFunction,NC>(existingValue)->Anchor.Equals(member->Anchor)) {
                                Lox_Error("Doubly defined member function.\n"
                                    "This happens with overloaded template functions that use keyword requires.\n"
                                    "To fix this, dox only one function and include in the dox that\n"
                                    "different versions for different requirements exist.\n"
                                    "  Function: {}::{}.\n"
                                    "  Tag-file first occurence:  {}:{}.\n"
                                    "  Tag-file this occurence:   {2}:{}.\n"
                                    , compoundTagName, key, FilePath
                                    , existingValue->LineNo
                                    , parser.lineNo )
                                throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                                key, compoundTagName, FilePath,
                                                existingValue->LineNo, member->LineNo);
                            }
                        }
                        else if ( member->IsA(Target::EnumElement)) {
                            // enum values of non-class enums appear doubly in the tag-file.
                            // We throw only in the case that the previous definition was
                            // different.
                            if (   !existingValue->IsA(Target::EnumElement)
                                || !existingValue->HTMLFile.Equals(member->HTMLFile)
                                || !Cast<TGTMember,NC>(existingValue)->Anchor.Equals(member->Anchor) )
                                throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                                key, compoundPathPortion, FilePath,
                                                existingValue->LineNo,
                                                member       ->LineNo);
 
                        }
                        else
                            throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                            key, compoundPathPortion, FilePath,
                                            existingValue->LineNo,
                                            member       ->LineNo);
                    }
 
                    // add the doc anchor(s) if present
                    parser.addDocAnchors(memberChild);
 
                    // if member type is enum, enum values might come now
                    while (parser.line.StartsWith("<enumvalue")) {
                        int lNo= parser.lineNo;
                        String256 elemName= parser.parseTag("enumvalue");
                        TGTEnumValue* enumElementTag= ma().New<TGTEnumValue>(
                                                  String(ma, parser.parseAttr("file")), lNo );
                        enumElementTag->Anchor  = String(ma, parser.parseAttr("anchor"));
                        Cursor elementCursor= memberChild.CreateChild(elemName, enumElementTag);
                        if ( elementCursor.IsInvalid() ) {
                            throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                            elemName, compoundPathPortion, FilePath,
                                            memberChild.Child(elemName).Value()->LineNo, parser.lineNo );
                        }
                        parser.nextLine();
                    }
 
                    // now we expect the end of the member
                    if (!parser.line.Equals("</member>"))
                        throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                        FilePath,parser.lineNo, "/member", parser.line);
 
                    continue;
                }
 
                // Tag <templarg> gives the template parameters of the type.
                // Not that specializations have their template parameters encoded in their name!
                if ( parser.line.StartsWith("<templarg"  ) ){
                    templateArgs[templateArgsSize++]=
                        String(static_cast<MonoAllocator&>(la), parser.parseTag("templarg"));
                             // todo: ^^^^why do we need to cast down here?
                    continue;
                }
 
                // ignore simple "announcements" of inner types
                if (    parser.line.StartsWith("<class"  )
                     && parser.line.EndsWith(  "</class>") )  continue;
 
                if ( parser.line.Equals(    "</compound>") ) break;
 
                // ignored tags
                if ( parser.line.StartsWith("<base"  ) ) {
                    ALIB_ASSERT_ERROR(tagRecord, "DXL/TAGFILE",
                                    "Base type information found for non-record type")
                    tagRecord->BaseTypes.push_back(parser.allocTag("base"));
                    continue;
                }
                
                if (kind == Target::Namespace) {
                    if ( parser.line.StartsWith("<namespace"  ) ) continue;
                    if ( parser.line.StartsWith("<concept"    ) ) continue;
                }
 
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath,parser.lineNo, "/compound", parser.line);
            }
 
            // add collected template args
            if (templateArgsSize) {
                ALIB_ASSERT_ERROR(tagRecord, "DXL/TAGFILE",
                                "Template args found for non-record type")
                tagRecord->TemplateArgs= ma().New<Target::TemplateArguments>();
                tagRecord->TemplateArgs->Count= templateArgsSize;
                tagRecord->TemplateArgs->Arguments= ma().NewArray<String>(templateArgsSize);
                for (int i= 0; i<templateArgsSize; ++i)
                    tagRecord->TemplateArgs->Arguments[i]= String(ma, templateArgs[i]);
            }
        }
        
        //-------------------------------  Compound Dir  --------------------------------------
        else if (   kind == Target::Dir  ){
            String256 path;
            Cursor dirCursor  = Root();
            String256 name    = parser.nextTag("name");
                      path    = parser.nextTag("path");
            ReplaceToTreeSeparator(path, kind);
            dirCursor.GoToCreatedPathIfNotExistent(path, &filePathComponentTag);
 
            // create node with TDir : Tag
            dirCursor= dirCursor.CreateChild(name, ma().New<TGTDir>( parser.allocNextTag("filename"),
                                                                     parser.lineNo ));
 
            for(;;) {
                parser.nextLine();
                parser.addDocAnchors(dirCursor);
 
 
                // ------------------- global members -----------
                if ( parser.line.StartsWith("<file>") ) continue;
                if ( parser.line.StartsWith("<dir>") ) continue;
                if ( parser.line.Equals(    "</compound>") )
                    break;
 
                // todo:don't throw, just warn
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath,parser.lineNo, "/compound", parser.line);
            }
        }
 
        //-------------------------------  Compound File  --------------------------------------
        else if (kind == Target::File){
            String256 path;
            Cursor fileCursor= Root();
            String256 name    = parser.nextTag("name");
                      path    = parser.nextTag("path");
            ReplaceToTreeSeparator(path, kind);
            fileCursor.GoToCreatedPathIfNotExistent(path, &filePathComponentTag);
 
            // doxygen sometimes adds the last name of the path (probably to avoid duplicates)
            if (   name.StartsWith(fileCursor.Name())
                && name.CharAt(fileCursor.Name().Length() ) == system::DIRECTORY_SEPARATOR )
                name.DeleteStart(fileCursor.Name().Length() +1 );
 
            // create node with TFile : Tag
            fileCursor= fileCursor.CreateChild(name, ma().New<TGTFile>(
                                    parser.allocNextTag("filename"), parser.lineNo));
            for(;;) {
                parser.nextLine();
                parser.addDocAnchors(fileCursor);
                // ------------------- global members -----------
                if ( parser.line.StartsWith("<member kind=") ) {
                    String512 key;
                    TGTMember* member= parser.readMember(key, kind);
                    if (!member) continue;
                    Cursor memberChild= fileCursor.CreateChild(key, member);
                    if ( memberChild.IsInvalid() ) {
                        fileCursor.AssemblePath(path);
                        ReplaceFromTreeSeparator(path, kind);
                        Cursor previous= fileCursor.Child(key);
                        // this is just strange: sometimes doxygen adds the very same
                        // member twice. We just ignore that.
                        // However, if just the anchor is different, then either DXL is
                        // wrong or a newer doxygen version does something different.
                        if (   Cast<TGTMember,NC>(previous)->Anchor != member->Anchor
                            || !previous.Value()->HTMLFile.Equals(member->HTMLFile) ) {
                            if ( previous.Value()->IsA(Target::Macro) ) {
                                Lox_Warning("Doubly defined preprocessor macro.\n"
                                    "This happens when a preprocessor constant or macro is defined twice within\n"
                                    "the same source file. This is not supported by Doxygen.\n"
                                    "Instead, exclude the second (and further) occurrences in the same file from\n"
                                    "doxygen and add all different uses to the first definition.\n"
                                    "  Preprocessor define: {}::{}.\n"
                                    "  Tag-file first occurence:  {}:{}.\n"
                                    "  Tag-file this occurence:   {2}:{}.\n"
                                    , path, key, FilePath
                                    , previous.Value()->LineNo
                                    , parser.lineNo )
                            } else if (!Cast<TGTMacro,NC>(previous.Value())->Anchor.Equals(member->Anchor)) {
                                Lox_Error("Doubly defined member {!Q} in tag-file path {}:1\n"
                                            "   First definition  @ {}:{}\n"
                                            "   Second definition @ {2}:{}", key, path, FilePath,
                                                          previous.Value()->LineNo, member->LineNo)
 
                                // todo: I think we should not throw. The error is enough.
                                //       Lets try to work as far as we can to continue to work with
                                //       upcoming releases.
                                //       So: find (and try to remove) all Exceptions::DuplicateChildName
                                //           and all exceptions anyhow!
                                throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                                key, path, FilePath,
                                                previous.Value()->LineNo, member->LineNo);
                        }   }
                    }
                    else
                        // add the doc anchor(s) if present
                        parser.addDocAnchors(memberChild);
 
                    continue;
                }
 
                if ( parser.line.Equals(    "</compound>") )
                    break;
 
// todo:
// a) check if these really occur (or if this is a copy/paste error)
// b) don't throw, just warn
// c) change this everywhere
 
 
                // we are not interested in the the other contents of file compounds.
                // we just check if there is something unexpected
                if ( parser.line.StartsWith("<includes"  ) ) continue;
                if ( parser.line.StartsWith("<concept"   ) ) continue;
                if ( parser.line.StartsWith("<class"     ) ) continue;
                if ( parser.line.StartsWith("<namespace" ) ) continue;
 
 
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath,parser.lineNo, "/compound", parser.line);
            }
        }
 
        //-------------------------------  Compound Group  --------------------------------------
        else if (kind == Target::Group){
            String128 name    = parser.nextTag("name");
            String    title   = parser.allocNextTag("title");
 
            // create compound entry
            Cursor groupCursor= Root().CreateChild(name, ma().New<TGTGroup>(
                               parser.allocNextTag("filename"), parser.lineNo, title));
            for(;;) {
                parser.nextLine();
                parser.addDocAnchors(groupCursor);
 
                // ------------------- global members -----------
                if ( parser.line.StartsWith("<member kind=") ) {
                    String512 key;
                    TGTMember* member= parser.readMember(key, kind);
                    if (!member) continue;
 
                    Cursor memberChild= groupCursor.CreateChild(key, member);
                    if ( memberChild.IsInvalid() ) {
                        String256 path;
                        groupCursor.AssemblePath(path);
                        Cursor previous= groupCursor.Child(key);
                        Lox_Warning("Doubly defined member {!Q} in tag-file path {}:1\n"
                                    "   First definition  @ {}:{}\n"
                                    "   Second definition @ {2}:{}"
                                    ,key, path, FilePath
                                    ,previous.Value()->LineNo, member->LineNo )
                    }
                    
                    // add the doc anchor(s) if present
                    parser.addDocAnchors(memberChild);
                    
                    continue;
                }
 
                if ( parser.line.Equals(    "</compound>") )
                    break;
 
                // we are not interested in the the other contents of file compounds.
                // we just check if there is something unexpected
                //if ( parser.line.StartsWith("<includes"  ) ) continue;
                //if ( parser.line.StartsWith("<concept"   ) ) continue;
                //if ( parser.line.StartsWith("<class"     ) ) continue;
                //if ( parser.line.StartsWith("<namespace" ) ) continue;
 
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath,parser.lineNo, "/compound", parser.line);
            }
        }
 
        //-------------------------------  Compound Page  --------------------------------------
        else if (kind == Target::Page){
            String128 name    = parser.nextTag("name");
            String    title   = parser.allocNextTag("title");
 
            // create compound entry
            Cursor pageCursor= Root().CreateChild(name, ma().New<TGTPage>(
                               parser.allocNextTag("filename"), parser.lineNo, title));
 
            for(;;) {
                parser.nextLine(); // this reads anchors!
                parser.addDocAnchors(pageCursor);
                
                if ( parser.line.Equals(    "</compound>") )
                    break;
 
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath,parser.lineNo, "/compound", parser.line);
            }
        }
 
        //-------------------------------  C++ 20 Concepts  --------------------------------------
        else if (kind == Target::Concept) {
            String256 name = parser.nextTag("name");
            auto htmlFile= parser.allocNextTag("filename");
            ReplaceToTreeSeparator(name, kind);
            Cursor cursor= Root();
            int qtyCreated= cursor.GoToCreatedPathIfNotExistent(name, &filePathComponentTag);
            if ( qtyCreated == 0 ) {
                Cursor previous= cursor.Child(name);
                if (    !previous.Value()->IsA(Target::Concept)
                     ||  previous.Value()->HTMLFile.Equals(htmlFile)   )
                    throw Exception(ALIB_CALLER_NULLED, Exceptions::DuplicateChildName,
                                    name, FilePath, previous.Value()->LineNo, parser.lineNo);
                Lox_Warning("Doubly defined concept {!Q}\n"
                            "   First definition  @ {}:{}\n"
                            "   Second definition @ {2}:{}",
                            name, FilePath, previous.Value()->LineNo, parser.lineNo)
            }
 
            // create node with TGTConcept value
            cursor.Value()= ma().New<TGTConcept>(htmlFile, parser.lineNo);
            parser.nextLine();
            if (!parser.line.Equals("</compound>"))
                throw Exception(ALIB_CALLER_NULLED, Exceptions::UnexpectedXMLTag,
                                FilePath, parser.lineNo, "/compound", parser.line);
        }
 
        else
            throw Exception(ALIB_CALLER_NULLED, Exceptions::UnknownKind,
                            FilePath,parser.lineNo, kind);
 
    }
 
    StatCtdLines= parser.lineNo;
    Lox_Verbose("Finished reading tag-file:  {}, maximum line width: ", FilePath, parser.maxWidth )
    ALIB_ASSERT_ERROR(parser.maxWidth < 1024, "DXL/TAGFILE", "Line buffer to small.")
}
 
void  Index::DumpTree(Index::Node branch) {
    if ( branch.IsInvalid())
        branch= Root();
    characters::AlignedCharArray<nchar, 50> spaces( ' ' );
    AString actIndent;
    Lox_SetDomain("DUMP", Scope::Method )
    Lox_SetPrefix( std::reference_wrapper(actIndent) )
 
    Lox_Info("Dumping tag-file: " )
    StringTreeIterator<Index::TreeType> stit;
    stit.SetPathGeneration(lang::Switch::On);
    stit.Initialize(branch.AsCursor(), lang::Inclusion::Exclude);
    while (stit.IsValid()) {
        ALIB_ALLOW_SPARSE_ENUM_SWITCH
        // ReSharper disable once CppDFAUnreachableCode
        Target& tag= *stit.Node().Value();
        actIndent.Reset(String(spaces.Buffer(), stit.CurrentDepth()*4 ));
        switch (tag.Kind()) {
            case Target::UNKNOWN_COMPOUND:
                Lox_Warning( "Unknown Compound: {}::{}\n"
                             "  Documented in:     {}\n"
                             "  Tag-file location: {}:{}",
                             stit.Path(), stit.Node().Name(),
                             tag.HTMLFile, FilePath, tag.LineNo )
                break;
 
            case Target::FILEPATH_COMPONENT: {
                Lox_Info(stit.Node().Name(), system::DIRECTORY_SEPARATOR)
            } break;
 
            case Target::File: {
                auto& data= *Cast<TGTFile,NC>(stit.Node());
                Lox_Info("File: ", data.HTMLFile)
            } break;
 
            case Target::Variable:
                Lox_Info("Variable: ", stit.Node().Name())
                break;
            case Target::Function:
                Lox_Info("Method:   ", stit.Node().Name())
                break;
            case Target::Typedef:
                Lox_Info("Typedef:  ", stit.Node().Name())
                break;
            case Target::Enumeration:
                Lox_Info("Enum:     ", stit.Node().Name())
                break;
            case Target::EnumElement:
                Lox_Info("Elem:  ", stit.Node().Name())
                break;
            case Target::Page:
            case Target::Group:
                ALIB_ERROR("DXL/DUMP", "Page/Group should not be read today" )
                break;
 
            case Target::Namespace: {
                const TGTNamespace* target= Cast<TGTNamespace,NC>(stit.Node());
                Lox_Info("{}:  ", target->Kind(), stit.Node().Name())
                break;
            }
            case Target::Struct:
            case Target::Class:
            case Target::Union: {
                const TGTRecord* target= Cast<TGTRecord,NC>(stit.Node());
                Lox_Info("{}:  {}<{}> : {}]", target->Kind(),
                            stit.Node().Name(), target)
                break;
            }
 
            case Target::Concept:{
                const TGTConcept* target= Cast<TGTConcept,NC>(stit.Node());
                Lox_Info("{}:  {}]", target->Kind(), stit.Node().Name())
                break;
            }
 
            case Target::Macro:
            default: {
                const Target* target= stit.Node().Value();
                Lox_Error("UNHANDLED KIND IN DUMP: ", target->Kind())
                break;
            }
        }ALIB_POP_ALLOWANCE
 
        stit.Next();
    }
}
 
} //namespace [dxl]