target.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of \dxl - 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".
//==================================================================================================
#ifndef HPP_DXL_TARGET
#define HPP_DXL_TARGET
#pragma once
//#include "dxl.hpp"
#include "ALib.EnumRecords.H"
#include "ALib.App.CLI.H"
#include "ALib.Files.H"
 
namespace dxl {
 
/// This class represents a doxygen XLink target.
/// The targets are read from doxygen tag-files, are inserted into the string tree implemented
/// with class #"dxl Index" and indexed by a hashtable within the same class.
class Target {
  public:
    /// The maximum number of template arguments to parse and compare.
    /// If exceeded, a parse error will be set for the XLink.
    static size_t   MAX_TEMPLATE_ARGS; // todo: set to 64, doc or what. (not constexpr, might be changed. Constexpr should be removed elsewhere also, like done here!)
    /// Enumerates the kinds of compounds found in a the Doxygen tagfile.
    enum Kinds : unsigned {
        // compounds
        Dir                 =  (1 << 0), ///< Denotes a source folder.
        File                =  (1 << 1), ///< Denotes a source file.
        Page                =  (1 << 2), ///< Denotes a page.
        Group               =  (1 << 3), ///< Denotes a group.
        DocAnchor           =  (1 << 4),  ///< Denotes a preprocessor definition.
 
        Namespace           =  (1 << 5), ///< Denotes a namespace.
        Struct              =  (1 << 6), ///< Denotes a struct.
        Class               =  (1 << 7), ///< Denotes a class.
        Union               =  (1 << 8), ///< Denotes a union.
        Concept             =  (1 << 9), ///< Denotes a C++20 concept.
 
        // member types
        Macro               =  (1 <<10),  ///< Denotes a preprocessor definition.
        Typedef             =  (1 <<11),  ///< Denotes a type definition.
        Variable            =  (1 <<12),  ///< Denotes a namespace- or member-variable.
        Function            =  (1 <<13),  ///< Denotes a namespace- or member-function.
        Enumeration         =  (1 <<14),  ///< Denotes an enumeration.
        EnumElement         =  (1 <<15),  ///< Denotes an enumeration element.
        GenericMember       =  (1 <<16),  ///< An unknown or uninteresting group member type.
 
        // special
        FILEPATH_COMPONENT  =  (1 <<17),  ///< A node of a file path (not a doxygen kind).
        UNKNOWN_COMPOUND    =  (1 <<18),  ///< This is set when creating paths to compounds. They should be
                                          ///< replaced later, with true compound types.
                                          ///< Otherwise a compound was not doxed!
        UNSPECIFIED         =  (1 <<19),  ///< Used with the field #"XLink::KindSpec;2".
        MAX_KIND            =  19,        ///< The highest bit defining a kind.
 
        ROOT                =  (1 <<20),   ///< The kind attached to the root node of the tree.
        UNRESOLVED          =  (1 <<21),   ///< The kind attached to the root node of the tree.
 
        /// Mask to identify member types. Here the word "member" is not meant in the C++ sense,
        /// but in the sense of "compound member"
        MEMBER              =  Macro + Typedef + Variable + Function + Enumeration + EnumElement,
 
        /// Mask to identify records types.
        RECORD              =  Struct + Class + Union,
 
        /// Mask to identify compound types.
        COMPOUND            =  RECORD + Namespace
 
    };
 
    /// A List of function argument types (strings).
    /// This is not a vector or list container, but a mono-allocated array of arguments.
    /// Construction and allocation is done with the static method #PARSE.
    ///
    /// The names of the arguments are left pruned. Furthermore, few standardizations in
    /// respect to spacing are performed. This enables to easily identify whether a given
    /// #"XLink" and a corresponding Target share the exact same parameters
    struct FunctionArguments {
        /// The number of arguments.
        int  Count;
 
        /// An array of length #Count of strings.
        alib::String* Arguments= nullptr;
 
      protected:
        /// Constructor.
        FunctionArguments()=                                                                default;
      public:
        /// Static method to parse an instance of this type from the given \p{src} and allocate
        /// the instance and its argument list in the given \p{ma}
        /// @param ma      The mono allocator to use.
        /// @param parser  The substring used for parsing. The round brackets and their contents
        ///                are removed when the method returns.
        /// @return The instance created and parsed.
        ///         If a syntax error occurs, \c nullptr is returned.
        static
        FunctionArguments* PARSE(alib::MonoAllocator& ma, alib::Substring& parser);
 
        /// Tests if the arguments \p{linkArgs} of an #"XLink" match the ones of a target.
        /// Not all the arguments need to match, and only substrings of the arguments need to be
        /// given to have a match (see return value). todo
        /// @param linkArgs   The arguments in the #"XLink".
        /// @param targetArgs The arguments in the target.
        /// @return
        ///   This method has five possible return values:
        ///   - \c 0 if arguments are given in the \p{linkArgs} and those do not match.
        ///   - \c 1 if the \xl has no arguments specified (or empty brackets), while the target
        ///        has arguments.
        ///   - \c 2 if no arguments are given in the \xl and the target has no arguments.
        ///   - \c 3 - if both instances have no arguments, or
        ///          - if both instances have arguments, and the ones in the \p{linkArgs} are a
        ///            subset, or one or more of the arguments are only partly given.
        ///   - \c 4 if both instances have arguments provided and they match exactly.
        ///          (This includes a given empty pair of brackets "()" on parameterless functions.)
        /// If each argument matches entirely, \c 3 is returned. This indicates to the caller that
        /// the arguments should be displayed in the XLink.
        static
        int MATCH(FunctionArguments* linkArgs, FunctionArguments* targetArgs);
 
        /// Prints the parsed argument types in a standardized format.
        /// @param dest The destination string. The string is not cleared.
        void               Print(alib::AString& dest);
    };
 
    /// A List of template arguments.
    /// This is not a vector or list container, but a mono-allocated array of arguments.
    /// Construction and allocation is done with the static method #PARSE.
    ///
    /// The names of the arguments are not given by doxygen, and, as far as we see, doxygen
    /// attaches those only to specializations of template types.
    /// (Not to the original type and not to templated functions.)
    ///
    /// A few standardizations in respect to spacing are performed. This enables to easily
    /// identify whether a given #"XLink" and a corresponding Target share the exact same
    /// parameters.
    struct TemplateArguments {
        /// The number of arguments.
        int  Count;
 
        /// An array of length #Count of strings.
        alib::String* Arguments ;
 
        /// Constructor.
        TemplateArguments() : Count{0} , Arguments{nullptr}                                       {}
 
        /// Static method to parse an instance of this type from the given \p{src} and allocate
        /// the instance and its argument list in the given \p{ma}
        /// @param ma      The mono allocator to use.
        /// @param parser  The substring used for parsing. The round brackets and their contents
        ///                are removed when the method returns.
        /// @return The instance created and parsed.
        ///         If a syntax error occurs, \c nullptr is returned.
        static
        TemplateArguments* PARSE(alib::MonoAllocator& ma, alib::Substring& parser);
 
        /// Tests if these template arguments found in an #"XLink" match the ones in the given
        /// target. Not all the arguments need to match, and only substrings of the arguments need
        /// to be given.
        /// If each argument matches entirely, \c 2 is returned.
        /// @param target The template arguments in the potential target.
        /// @return \c 0 if the arguments do not match, \c 1 if the arguments match but are not
        ///         completely given, and \c 2 if they are given in the exact specification.
        int Match(TemplateArguments& target);
 
        /// Prints the parsed argument types in a standardized format.
        /// @param dest The destination string. The string is not cleared.
        void               Print(alib::AString& dest);
    };
 
    /// Statistics.
    /// Counts the number of targets of each kind.
    class KindStats { // todo not used in output, yet
      protected:
        /// The counted number of elements for each kind.
        int  count[size_t(MAX_KIND)];
 
      public:
        /// Constructor.
        KindStats() { std::fill_n(count, size_t(alib::lang::MSB(unsigned(MAX_KIND))-1), 0); }
 
        /// Counts the given kind.
        /// @param pKind The kind to count.
        void Add(Kinds pKind) {
            size_t idx= size_t(alib::lang::MSB(unsigned(pKind)) - 1);
            ALIB_ASSERT(idx < sizeof(count)/sizeof(int), "DXL/TAGFILE" )
            ++count[idx];
        }
 
        /// Returns the number of entities of a given kind parsed from the tag-file.
        /// @param pKind The kind to receive the quantity for.
        /// @return The quantity of kinds of given kind \p{pKind}.
        int Get(Kinds pKind) {
            size_t idx= size_t(alib::lang::MSB(unsigned(pKind)) - 1);
            ALIB_ASSERT(idx < sizeof(count)/sizeof(int), "DXL/TAGFILE" )
            return count[idx];
        }
 
        /// Returns the number of entities of a given kind parsed from the tag-file.
        /// @param kindIdx The kind-index to receive the quantity for.
        /// @return The quantity of kinds of given \p{kindIdx}.
        int GetByIdx(int  kindIdx) {
            ALIB_ASSERT(kindIdx>=0 && kindIdx < int(sizeof(count)/sizeof(int)), "DXL/TAGFILE" )
            return count[kindIdx];
        }
    };
 
  protected:
    Kinds           kind; ///< The kind of this target.
 
  public:
 
    /// The line number in the Doxygen tag-file where this entity is defined.
    int             LineNo;
 
    /// The HTML file that this target links to (or into).
    alib::String    HTMLFile;
 
  protected:
    /// Constructor.
    /// @param pKind    The kind of this target.
    /// @param htmlFile The html file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    Target(Kinds pKind, const alib::String& htmlFile, int lineNo)
    : kind(pKind)
    , LineNo(lineNo)
    , HTMLFile{htmlFile}                                                                          {}
 
public:
    /// Returns the kind of this target. The result may be used to cast a pointer to the
    /// corresponding descendant
    /// @return The kind of this target.
    Kinds Kind() const { return Kinds( unsigned(kind) & unsigned( (1 << int(MAX_KIND))-1)); }
 
    /// Tests if an instance is of a given \p{aKind}.
    /// @param aKind The kind to test this instance for.
    /// @return \c true if this instance is of the given \p{kind}, \c false otherwise.
    bool IsA(Kinds aKind) const {
        return (unsigned(kind) & unsigned(aKind)) != 0;
    }
 
    /// Static method that returns a likewise static target which class #"dxl::Index" attaches to its
    /// #"StringTree"'s root-node.
    /// @return A pointer to the target of type #"Target::ROOT".
    static Target* GetRootNodeTarget() {
        static Target RootNodeTarget(ROOT, alib::NULL_STRING,  0);
        return &RootNodeTarget;
    }
};
 
/// This is not a 'real' XLink target. It is created with nodes in the #"StringTree" of class
/// #Index that represent a segment of the path to a source file.
struct TGTFilePathComponent : Target {
    /// Constructor.
    /// @param lineNo The line number that this path component occured in the tag-file for the
    ///               first time.
    TGTFilePathComponent(int lineNo) : Target(FILEPATH_COMPONENT, alib::NULL_STRING, lineNo) {}
};
 
/// XLink target information for source files.
struct TGTDir : Target {
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTDir(const alib::String& htmlFile, int lineNo) : Target(Dir, htmlFile, lineNo) {}
};
 
/// XLink target information for source files.
struct TGTFile : Target {
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTFile(const alib::String& htmlFile, int lineNo) : Target(File, htmlFile, lineNo) {}
};
 
/// XLink target information for groups.
struct TGTGroup : Target {
    /// The title of the group.
    alib::String    Title;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    /// @param title    The title of the group.
    TGTGroup(const alib::String& htmlFile, int lineNo, alib::String& title)
    : Target(Group, htmlFile, lineNo)
    , Title{title}                                                  {}
};
 
/// XLink target information for pages.
struct TGTPage : Target {
    /// The title of the group.
    alib::String    Title;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    /// @param title    The title of the page.
    TGTPage(const alib::String& htmlFile, int lineNo, alib::String& title)
    : Target(Page, htmlFile, lineNo)
    , Title{title}                                                  {}
};
 
/// XLink target information for pages.
struct TGTDocAnchor : Target {
    /// The key of the anchor. This is redundant with its node name, but needed, as anchors
    /// of members can be inserted only after the member was read.
    alib::String    Name;
 
    /// The title of the group.
    alib::String    Title;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    /// @param name     The name (key) of the anchor.
    /// @param title    The title of the anchor.
    TGTDocAnchor(const alib::String& htmlFile, int lineNo, alib::String& name, alib::String& title)
    : Target(DocAnchor, htmlFile, lineNo)
    , Name{name} 
    , Title{title}                                                  {}
};
 
/// XLink target information for C++ concepts.
struct TGTConcept : Target {
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTConcept(const alib::String& htmlFile, int lineNo) : Target(Concept, htmlFile, lineNo) {}
};
 
/// XLink target information for C++ namespaces.
struct TGTNamespace : Target {
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTNamespace(const alib::String& htmlFile, int lineNo) : Target(Namespace, htmlFile, lineNo)       {}
};
 
/// XLink target information for C++ structs, classes and unions.
struct TGTRecord : Target {
    /// Template arguments provided with tags <c><templarg></c>.
    TemplateArguments*  TemplateArgs      = nullptr;
 
    /// Template specialization arguments. Those are encoded in the name, leaving the types out
    /// and just giving the name of the arguments.
    TemplateArguments*  SpecializationArgs= nullptr;
 
    /// The base type of the record
    alib::ListMA<alib::String>        BaseTypes;
 
    /// Constructor.
    /// @param ma       The mono allocator to use.
    /// @param pKind    The (derived) kind of this target.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTRecord(alib::MonoAllocator& ma, Kinds pKind, const alib::String& htmlFile, int lineNo)
    : Target(pKind, htmlFile, lineNo)
    , BaseTypes{ma} {}
};
 
/// XLink target information base type for targets which are members of other entities.
/// See derived types.
struct TGTMember : Target {
    /// The HTML anchor.
    alib::String    Anchor  = nullptr;
 
    /// This ID is (sometimes) set if the member is read from a \b Doxygen group.
    alib::String    RefID  = nullptr;
 
    /// Constructor.
    /// @param pKind    The (derived) kind of this target.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTMember(Kinds pKind, const alib::String& htmlFile, int lineNo) : Target(pKind, htmlFile, lineNo) {}
};
 
/// A generic member type. These are used, \#if defined(ALIB_DOX)
/// - this version of \dxl does not know the member kind and cannot parse it specifically
/// - the member appeared in a group compound and is not further processed by \dxl.
struct TGTGenericMember : TGTMember {
 
    /// The kind of the member, which was not fully read.
    Target::Kinds Kind;
 
    /// Constructor.
    /// @param pKind    The (derived) kind of this target.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTGenericMember(Kinds pKind, const alib::String& htmlFile, int lineNo)
    : TGTMember(Target::GenericMember, htmlFile, lineNo), Kind{pKind} {}
};
 
 
 
/// XLink target information for C++ preprocessor definitions.
struct TGTMacro : TGTMember {
    /// The list of arguments.
    FunctionArguments* Args        = nullptr;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
   TGTMacro(const alib::String& htmlFile, int lineNo) : TGTMember(Macro, htmlFile, lineNo) {}
};
 
 
/// XLink target information for C++ enum elements.
struct TGTEnumValue : TGTMember {
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
   TGTEnumValue(const alib::String& htmlFile, int lineNo) : TGTMember(EnumElement, htmlFile, lineNo) {}
};
 
/// XLink target information for type definitions.
struct TGTTypedef : TGTMember {
    /// The type of the definition.
    alib::String    Type    = nullptr;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTTypedef(const alib::String& htmlFile, int lineNo)
    : TGTMember(Typedef, htmlFile, lineNo) {}
};
 
/// XLink target information for C++ enums.
struct TGTEnumeration : TGTMember {
    /// The underlying type of the \c enum.
    alib::String    Type    = nullptr;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTEnumeration(const alib::String& htmlFile, int lineNo)
    : TGTMember(Enumeration, htmlFile, lineNo) {}
};
 
 
 
/// XLink target information for C++ namespace- and member-variables.
struct TGTVariable : TGTMember {
    /// The type of the variable
    alib::String    Type    = nullptr;
 
    /// The subscript of the variable.
    alib::String    Subscript    = nullptr;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTVariable(const alib::String& htmlFile, int lineNo) : TGTMember(Variable, htmlFile, lineNo) {}
};
 
/// XLink target information for C++ namespace- and member-functions.
struct TGTFunction : TGTMember {
    /// The return type of the function or method.
    alib::String        Type        = nullptr;
 
    /// The list of arguments.
    FunctionArguments*  Args        = nullptr;
 
    /// Additional qualifiers like \c const or \c nothrow.
    alib::String        Qualifiers  = nullptr;
 
    /// Constructor.
    /// @param htmlFile The HTML file that this instance targets.
    /// @param lineNo   The definition line number in the Doxygen tag-file.
    TGTFunction(const alib::String& htmlFile, int lineNo) : TGTMember(Function, htmlFile, lineNo) {}
};
 
} //namespace [dxl]
 
ALIB_ENUMS_MAKE_BITWISE( dxl::Target::Kinds)
ALIB_CAMP_ENUM( dxl::Target::Kinds, alib::enumrecords::ERSerializable, alib::APPCLI_CAMP, "Kinds" )
 
// #################################################################################################
// ##############################  Casts    ########################################################
// #################################################################################################
 
namespace dxl {
 
#include "ALib.Lang.CIFunctions.H"
 
/// Casts the given #"dxl Target" pointer to the requested derived type \p{TGT}. In case of fai3lure
/// returns \c nullptr.
/// @tparam TGT    The requested target type.
/// @tparam TCheck If #"alib::NC" is given, no check whether the right kind is contained in
///                this target is performed. Defaults to #"alib::CHK".
/// @param target  The instance to cast.
/// @return The cast type or \c nullptr if \p{target} is not of the requested type.
template<typename TGT, typename TCheck= alib::CHK>
requires     std::derived_from<TGT, Target>
          && ( std::is_same_v<TCheck, alib::CHK> || std::is_same_v<TCheck, alib::NC> )
const TGT* Cast(const Target* target) {
    if constexpr (std::is_same_v<TCheck, alib::CHK>) {
        if constexpr (std::is_same_v<TGT, TGTGroup        >)            { return target->IsA(Target::Group        ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTPage         >)            { return target->IsA(Target::Page         ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTDocAnchor    >)            { return target->IsA(Target::DocAnchor    ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTRecord       >)            { return target->IsA(Target::RECORD       ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTMember       >)            { return target->IsA(Target::MEMBER       ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTGenericMember>)            { return target->IsA(Target::GenericMember) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTMacro        >)            { return target->IsA(Target::Macro        ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTTypedef      >)            { return target->IsA(Target::Typedef      ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTEnumeration  >)            { return target->IsA(Target::Enumeration  ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTVariable     >)            { return target->IsA(Target::Variable     ) ? static_cast<const TGT*>(target) : nullptr;}
        if constexpr (std::is_same_v<TGT, TGTFunction     >)            { return target->IsA(Target::Function     ) ? static_cast<const TGT*>(target) : nullptr;}
        ALIB_ERROR( "DXL/TAGFILE", "Cast not implemented yet." )
        return nullptr;
    } else {
        ALIB_ASSERT_ERROR(
            (std::is_same_v<TGT, TGTGroup        >             &&  target->IsA(Target::Group        ) )
         || (std::is_same_v<TGT, TGTPage         >             &&  target->IsA(Target::Page         ) )
         || (std::is_same_v<TGT, TGTDocAnchor    >             &&  target->IsA(Target::DocAnchor    ) )
         || (std::is_same_v<TGT, TGTRecord       >             &&  target->IsA(Target::RECORD       ) )
         || (std::is_same_v<TGT, TGTMember       >             &&  target->IsA(Target::MEMBER       ) )
         || (std::is_same_v<TGT, TGTGenericMember>             &&  target->IsA(Target::GenericMember) )
         || (std::is_same_v<TGT, TGTMacro        >             &&  target->IsA(Target::Macro        ) )
         || (std::is_same_v<TGT, TGTTypedef      >             &&  target->IsA(Target::Typedef      ) )
         || (std::is_same_v<TGT, TGTEnumeration  >             &&  target->IsA(Target::Enumeration  ) )
         || (std::is_same_v<TGT, TGTVariable     >             &&  target->IsA(Target::Variable     ) )
         || (std::is_same_v<TGT, TGTFunction     >             &&  target->IsA(Target::Function     ) )
         , "DXL/TAGFILE", "Cast not implemented yet." )
        
        return static_cast<const TGT*>(target);
    }
}
 
/// Overload of #"Cast(const Target*)" which works with references and calls its non-checking version.
/// @tparam TGT    The requested target type.
/// @param target  The instance to cast.
/// @return The cast type or \c nullptr if \p{target} is not of the requested type.
template<typename TGT>
requires     std::derived_from<TGT, Target>
TGT& Cast(Target& target) { return *Cast<TGT,alib::NC>(&target); }
 
#include "ALib.Lang.CIMethods.H"
 
} //namespace [dxl]
 
 
#endif // HPP_DXL_TARGET