xlink.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_XLINK
#define HPP_DXL_XLINK
#pragma once
#include "target.hpp"
#include "styles.hpp"
#include "index.hpp"
#include "ALib.FileTree.H"
#include "dxl.hpp"
 
namespace dxl {
class XLink;
class  DoxygenXLinks;
 
/// A location of an XLink in a source or HTML file.
struct Location {
    alib::filetree::FTFile   File;       ///< The file's node, either in #"fTreeSources;2" or
                                    ///< #"fTreeHTML;2".
    int                 Line;       ///< The line number of the XLink.
    int                 Column;     ///< The column in the #Line.
};
 
 
/// Entries of a list of XLink instances found in a source file.
/// Instances represent an XLink to a doxygen #"dxl Target" as given by the user.
struct ResolvedLocation {
    XLink*              XL;         ///< The corresponding XLink.
    int                 Line;       ///< The line number of the XLink.
    int                 Column;     ///< The column in the #Line.
};
 
/// This type is #"FTFile::AttachCustomData;attached" to file tree nodes of source files.
/// It lists all places of links in the file.
using XLinkList = alib::StdVectorMA<ResolvedLocation>;
 
//##################################################################################################
/// Encapsulates the information given with the links that this whole project was created for.
/// Instances represent an XLink to a doxygen #"dxl Target" as given by the user.
//##################################################################################################
class XLink {
  public:
    #if ALIB_DEBUG
    friend void DbgUnitTests(DoxygenXLinks*);
    #endif
 
 
    /// The maximum number of scope hints and parents.
    static constexpr int MAX_SCOPE_DEPTH= 20;
 
    /// Possible results when parsing source links.
    enum class Errors {
        OK                       = 0, ///< No error or warning.
        TooManyParentsRequested  = 1, ///< Warning: The display requested more parents to include
                                      ///< than available.
        AnchorHasNoTitle         = 2, ///< Warning: An anchor without a title was used without
                                      ///< providing a user-defined display string. \dxl inserts
                                      ///< the anchor name in this case.
        InappropriateDisplayTweak= 3, ///< A display tweak was given that is not applicable to the
                                      ///< resolved target type.
 
        WARNINGMARKER            = 4, ///< This is a marker-element that separates warnings from
                                      ///< Errors.
 
        Empty                    = 5, ///< The search string was empty (apart from possible
                                      ///< whitespaces).
        NoTargetNameGiven        = 6, ///< No target identifier was given.
        TooManyScopeHints        = 7, ///< Too many scope-hints (words separated with spaces) were
                                      ///< given.
        ScopeTooDeep             = 8, ///< The number of nested scope (namespaces/compounds) is too
                                      ///< huge.
        UnknownUnderlyingType    = 9, ///< The underlying type requested with '^' was not found.
        IllegalTargetKind        =10, ///< The target kind specification must be "!k " with k being a
                                      ///< valid kind identification-character and a space following.
        LocalLinkWithScopeHints  =11, ///< A local XLink (aka the identifier section starts with
                                     ///< \c '.') must not have scope hints.
                                     ///
        /// This error occurs with the command line option <c>--doxyfy</c>.
        /// As explained in the chapter #"dxl_manual_addfeat_doxyfication", certain local links
        /// cannot be restored back to \b Doxygen's <c>\\ref</c> command if they occur in different
        /// HTML files.
        RestoringAmbiguousLocalLink = 12,
 
        /// This error occurs with the command line option <c>--doxyfy</c>.
        /// It is issued when a local XLink is found in the source-copy to be restored, which has
        /// not been found in the HTML files. This usually indicates a wrong setup of the
        /// documentation build steps.
        RestoringUnusedLocalLink    = 13,
 
        /// This error occurs with local links that appear in HTML-files that are not found in
        /// the index (tag-file). For example, if a local link is used in the short description
        /// of a class and this class then appears in "hierarchy.html"
        LocalLinkCopiedToUnrecognizableFile = 14,
 
    };
 
    /// The mono allocator used to create the members of the class.
    alib::MonoAllocator                     MA;
 
    /// The lock protecting the creation phase and as well allocator access.
    alib::Lock                              Lock;
 
  protected:
    /// An array of identifiers listed in the source XLink. The first members of the list are
    /// 'hints' given by the user separated by spaces. Those hints are used with a substring search
    /// in a component path.<br>
    /// The rest of the list represents fully-named parents and finally the component itself.
    /// The separation and length of the list is given with the fields #scopeHintsSize and
    /// #scopeSize.
    alib::String*                           scope;
 
    /// The number of strings in the array #scope that are only hints.
    int                                     scopeHintsSize;
 
    /// The number of strings in the array #scope. Up to index #scopeHintsSize <c> - 1</c>
    /// the strings are only hints. The remaining represent full parent paths.
    int                                     scopeSize                                            =0;
 
    /// Inner main method of #"AssembleDisplay()".
    void                                    assembleDisplay();
 
  public:
    /// The original source string.
    alib::String                            LinkString;
 
    /// Function arguments provided with the source XLink.
    Target::FunctionArguments*              Args                                           =nullptr;
 
    /// Template arguments provided at the beginning of the source XLink, before path hints and
    /// the path, optionally introduced by the keyword \c template.
    Target::TemplateArguments*              TemplateArgs                                   =nullptr;
 
    /// Template arguments provided at the end of the source XLink, before the optional display,
    /// hence after the entity name.
    Target::TemplateArguments*              SpecializationArgs                             =nullptr;
 
    /// Function qualifiers like \c const, or \c nothrow provided with the source XLink.
    alib::String                            Qualifiers                                     =nullptr;
 
    /// A variable subscript provided by the source XLink.
    alib::String                            Subscript                                      =nullptr;
 
    /// An XLink to the parent scope. Created with #GetLinkToParent in the case a parent scope was
    /// given and some search results are not found in this %XLink directly.
    XLink*                                  linkToParentScope                              =nullptr;
 
    /// The name of the entity to find (namespace, record, variable, function, enumeration element,
    /// type definition, etc).<br>
    /// If <b>"*"</b> is given, the following rules apply:
    /// - Besides the entity name, the given parent paths is displayed (not the path hints).
    /// - In case of a function, all parameters are appended.
    /// - In case of a template type, the keyword <c>typename<...></c> with the list of
    ///   all template parameters is prepended. <- This is a TODO(251221 08:27):
    /// - In case of a template specialization, the list of specialization types <c><...></c>
    ///   is appended.                          <- This is a TODO(251221 08:27):
    alib::String                            Display                                        =nullptr;
 
    /// Same as #Display but #"ConvertASCIItoHTMLEntities;HTML-encoded".
    alib::String                            DisplayHTMLEncoded                             =nullptr;
 
    /// The position of the display string in the original search string.
    /// Note: This information is solely needed for implementing the
    /// #"alib_mod_expressions;ALib expression" function #"DXLExpression;LinkDisplay"
    alib::integer                           DisplayOriginalPos                                   =0;
 
    /// This is a list of HTML styles to apply to the link. The list is created in the method
    /// #AssembleDisplay.
    Styles                                  CSSClasses;
 
    /// The list of results. Only when this list contains exactly one element, the XLink was
    /// successfully resolved.
    alib::StdVectorMA<Index::SearchResult>  Targets;
 
    /// A list of copies of this link, which is filled when disambiguation was (only) possible
    /// through the link's HTML file name. In this case, the same link, for example, "Size"
    /// can be dissolved into various different targets.
    /// This whole concept makes things a little complicated but allows easy linking to
    /// local members!
    XLink*                                  NextLocal                                       =nullptr;
 
    /// The tree node of the HTML file that created this copy of the originally given local \xl.
    alib::filetree::FTree::ConstCursorHandle  HTMLFileOfLocalLink                               = 0;
 
    /// The entity in the string tree that corresponds to the HTML file given with
    /// the field #".HTMLFileOfLocalLink".
    Index::ConstCursorHandle                LocalLinkEntity                                      = 0;
 
    /// List of nodes pointing to inherited base types. This is used to find inherited members.
    /// Created only if this XLink includes a parent specification and if during the search potential
    /// results come up that may be inherited, while no other results exist, yet.
    alib::ListMA<Index::Node>*              BaseTypes= nullptr;
 
    /// List of nodes pointing to type definition targets. This is used to find members which
    /// were addressed through type definitions.
    alib::ListMA<Index::Node>*              TypeDefinitionTargets= nullptr;
 
    /// A list of target nodes with the same name.
    alib::StdVectorMA<Index::Node>          DidYouMeanSameName;
 
    /// A list of functions matching by name but not by parameters. Filled per Index only in case
    /// a function was searched (parameter hints given in the XLink) and no match was found.
    /// But even if filled, a different index might provide a hit.
    alib::StdVectorMA<Index::Node>          DidYouMeanFunctionOverload;
 
    /// The (non-specialized) template type that matches an XLink, but either the link has
    /// different template parameters or a specialization was searched but not found.
    Index::Node                             DidYouMeanTemplateType;
 
    /// A list of entries that are variables, while the \xl's subscript does not match.
    alib::StdVectorMA<Index::Node>          DidYouMeanVariable;
 
    /// A list of entries that are not templates, while a template type was searched.
    alib::StdVectorMA<Index::Node>          DidYouMeanNotATemplate;     // todo not used yet
 
    /// A list of specializations whose paths were matching the search pattern, but the
    /// specialization parameters did not fit. Also, non-specialized types that fit are put here.
    alib::StdVectorMA<Index::Node>          DidYouMeanSpecializations;
 
    /// The list of locations in source files. This list is unsorted as it is collected by
    /// the thread pool workers.
    alib::StdVectorMA<Location>             SourceLocations;
 
    /// The list of locations in HTML files. This list is unsorted as it is collected by
    /// the thread pool workers.
    alib::StdVectorMA<Location>             HTMLLocations; // todo: die landen nun teilweise in den local links
 
    /// Possible errors that occured during parsing the search string given by the user.
    Errors                                  Error                                       =Errors::OK;
 
    /// Function arguments provided with the source XLink.
    Target::Kinds                           KindSpec                           =Target::UNSPECIFIED;
 
 
    /// This flag is set when the specified link identifier starts with a dot character <c>'.'</c>.
    /// In this case, the \xl processing is changed in various ways.
    bool                                    IsLocal                                          =false;
 
    /// This flag is set when the specified link identifier was not found in the HTML files.
    bool                                    NotFoundInHTML                                   =false;
 
    /// This flag is set if <c>"^"</c> is given at the start of the XLink which suppresses
    /// warnings if linking indirectly through base types or type definitions (or both).
    bool                                    NoIndirectionWarning                             =false;
 
    /// This flag is set if <c>"^"</c> is given at the start of the XLink and the target is
    /// a type definition and it's parent is not a record (or the parent was not given).<br>
    /// Note that this flag is set only after the link is resolved in the method #"GetXLink".
    /// Before (namely after parsing the link and during the search and disambiguation process)
    /// instead the flag #NoIndirectionWarning is set. The latter then is cleared.
    bool                                    IsUnderlyingTypeDef                              =false;
 
    /// This flag is used with the final output generation to prevent double printing when
    /// walking through the source file tree and the file's list of XLink-locations.
    bool                                    WasPrinted                                       =false;
 
    /// Helper that searches the target of a type definition. Supports:
    /// - chained type definitions, and
    /// - type definitions whose target type is local to the namespace of the type definition.
    /// @param startCursor      A reference to the cursor that points to the type definition.
    /// @param origSearchString The original search string. This is used for log-output only.
    /// @return The target cursor. On failure, this will be a root cursor.
    static
    Index::Node ResolveTypeDef( const Index::Node& startCursor,
                                  const alib::String& origSearchString );
 
    /// Recursive helper used by #"Index::Search" to find inherited parents.
    /// @param bases   The list of base types.
    void   findInherited( const decltype(TGTRecord::BaseTypes)&    bases);
 
    /// Constructor. Parses the given \p{searchString} and allocates the fields in the \p{ma}.
    XLink()
    : MA(ALIB_DBG("DLXLink",) 1 ) // todo: Check if 1 is enough. Should be!
    , Targets                         {MA}
    , DidYouMeanSameName              {MA}
    , DidYouMeanFunctionOverload      {MA}
    , DidYouMeanVariable              {MA}
    , DidYouMeanNotATemplate          {MA}
    , DidYouMeanSpecializations       {MA}
    , SourceLocations                 {MA}
    , HTMLLocations                   {MA}  { ALIB_DBG( MA.DbgCriticalSectionsPH->DCSLock= &Lock); }
 
    /// This method is need for the unit-tests and available only with debug-compilations.
    void DbgReset() {
        alib::lang::Destruct(*this);
        new (this) XLink();
        ALIB_DBG(MA.DbgCriticalSectionsPH.Construct(nullptr));
    }
 
    /// Parses the given \p{searchString} and allocates the fields in the #MA.
    void            Parse();
 
    /// Creates (once) and returns an XLink targeting the parent-scope of this XLink.
    /// The returned XLink is already resolved and its #Targets can be iterated.<br>
    /// This function is used to find inherited- and type-definition-members.
    /// It furthermore creates and fills the field #BaseTypes.
    ///
    /// This function will be called by #"Index::Search" only in the case that this XLink contains a
    /// parent specification.
    /// @return The requested XLink.
    XLink*          GetLinkToParent();
 
    /// @return The number of strings in the array #scope that are only hints.
    int             HintsSize()                                     const { return scopeHintsSize; }
 
    /// The number of strings in the array #scope. Up to index <c>scopeHintsSize - 1</c>
    /// the strings are only hints. The remaining represent full parent paths.
    /// @return The number of strings in the array #scope.
    int             ScopeSize()                      const { return scopeSize - scopeHintsSize -1; }
 
    /// @return A scope-parent specified in this XLink.
    /// @param n The number of the parent to get.
    const alib::String&   Scope(int n)                                                         const
    { ALIB_ASSERT(n >= 0 && n < ScopeSize(), "DXL/XLINK") return scope[scopeHintsSize + n]; }
 
    /// @return A scope-hint specified in this XLink.
    /// @param n The number of the hint to get.
    const alib::String&   Hint(int n)                                                          const
    { ALIB_ASSERT(n >= 0 && n < HintsSize(), "DXL/XLINK") return scope[n]; }
 
    /// @return The last component of the given path.
    alib::String&   Name()    const { ALIB_ASSERT(scopeSize>0, "DXL/XLINK") return scope[scopeSize - 1];}
 
    /// @returns \c true, if this link was not only registered, but also parsed.
    bool            IsParsed()                 const { return scopeSize > 0 || Error!= Errors::OK; }
 
    /// @returns \c true, if exactly one match was found, \c false otherwise.
    bool            IsResolved()                               const { return Targets.size() == 1; }
 
    /// @returns \c true, if this links has errors (other than not resolved or ambiguous).
    bool            HasErrors()                      const { return Error > Errors::WARNINGMARKER; }
 
    /// @param ignoreIndirects If \c true is given, indirect links which are not marked as such,
    ///                        are not listed in the error/warning output.
    /// @returns \c true, if this link has warnings.
    bool            HasWarnings(bool ignoreIndirects) {
        return    (    Error != Errors::OK
                    && Error < Errors::WARNINGMARKER )
               || (    !ignoreIndirects
                    && !IsLocal
                    && (NoIndirectionWarning!=(    Result().IsIndirectByInheritance
                                                || Result().IsIndirectByTypeDef
                                                || Result().IsIndirectLinkToScannedHTMLSourceFile)
                       )                       );
    }
    /// @param ignoreIndirects Passed to internally used method #".HasWarnings".
    /// @returns \c true, if exactly one match was found, \c false otherwise.
    bool            IsGood(bool ignoreIndirects) {
        return  IsResolved() &&  !HasErrors()  &&  !HasWarnings(ignoreIndirects);
    }
 
    /// @returns The result if #IsResolved returns \c true. Otherwise, this is undefined behavior.
    ///          In debug-builds, an #"Raise;ALib assertion" is raised, if #IsResolved is \c false.
    Index::SearchResult& Result() {
        ALIB_ASSERT_ERROR(IsResolved(), "DXL/XLINK",
            "XLink is not resolved. Method Result() must not be invoked.")
        return Targets.front();
    }
 
    /// @returns The result if #IsResolved returns \c true. Otherwise, this is undefined behavior.
    ///          In debug-builds, an #"Raise;ALib assertion" is raised, if #IsResolved is \c false.
    const Index::SearchResult& Result()                                                      const {
        ALIB_ASSERT_ERROR(IsResolved(), "DXL/XLINK",
            "XLink is not resolved. Method Result() must not be invoked.")
        return Targets.front();
    }
 
    /// Assembles the display string #Display, if not already set.
    /// Called when an XLink was successfully resolved (size in #Targets is 1).
    void    AssembleDisplay() {
        assembleDisplay();
        if( !NeedsHTMLConversion(Display))
            DisplayHTMLEncoded= Display;
        else {
            alib::String2K htmlDisplay;
            ConvertASCIItoHTMLEntities(Display, htmlDisplay);
            DisplayHTMLEncoded= alib::String(MA, htmlDisplay );
        }
    }
 
    /// Writes a human-readable message on unresolved or ambiguous links.
    /// @param out           The target output paragraph formatter.
    /// @param linkString    The original XLink string found in the output (and sources).
    /// @param suppressHints If given as \c true, no hints are printed.
    void PrintError(alib::Paragraphs& out, const alib::String& linkString,
                    bool suppressHints= false);
 
    /// Returns this or a new \xl instance, with the given file attached.
    /// New copies are attached to the pointer #".NextLocal", which implements a forward list.
    /// @param htmlFile The file that the local link was found in.
    /// @return An \xl with the given \p{htmlFile} set.
    std::pair<XLink*,bool>  GetLocalCopy(const alib::filetree::FTFile& htmlFile);
 
    /// Returns the number of local copies, hence the number of different HTML-files that this
    /// local link appeared in.
    /// @return The number of local copies.
    int                     CountLocalCopies() {
        if( !HTMLFileOfLocalLink.IsValid())
            return 0;
        int n= 1;
        XLink* l= this;
        while((l= l->NextLocal))
            ++n;
        return n;
    }
 
};
 
} //namespace [dxl]
 
 
#endif // HPP_DXL_XLINK