dxl.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_DOXYGEN_LINKER
#define HPP_DOXYGEN_LINKER
#pragma once
 
 
#include "dxlapp.hpp"
#include "threadpool.hpp"
#include "doxyfile.hpp"
#include "xlink.hpp"
#include "ALib.ThreadModel.H"
#include "ALib.Files.H"
#include "ALib.CLI.H"
#include "ALib.ThreadModel.H"
#include "ALib.Containers.StringTreeIterator.H"
#include "exclamations.hpp"
 
 
#if defined(__clang__)
_Pragma("clang diagnostic push")
_Pragma("clang diagnostic ignored \"-Wheader-hygiene\"")
#endif
 
#if !DOXYGEN
using namespace std::literals::chrono_literals;
#endif
 
#if defined(__clang__)
_Pragma("clang diagnostic pop")
#endif
 
/// todox
namespace dxl {
class Index;
class DXLExpression;
 
// todo
// [ ] It might be useful to have an option to print out all Records which have never been
//     linked to in the documentation. For this, type Target needs to get a hit-counter.
 
/// A preprocessor constant defined in file #"F;dxl.hpp".
#define TEST_CONSTANT  "In file dxl.hpp"
#undef  TEST_CONSTANT
 
/// This is the first definition in this file.
#define TEST_REDEFINED  "ORIGINAL"
#undef  TEST_REDEFINED
 
/// ...wile this is the second definition in this file.
#define TEST_REDEFINED  "REDEFINED"
#undef  TEST_REDEFINED
 
/// This type definition is not used in the code.
/// It is for testing in manual section #"dxl_styling".
using XLinkType= dxl::XLink;
 
/// This union is not used in the code.
/// It is for testing in manual section #"dxl_styling".
union DXLTestUnion {
    int    i; ///< In \c int.
    double d; ///< In \c double.
};
 
 
/// This type definition is not used in the code. It is for testing whether \dxl finds members
/// through chained type definitions.
using ChainedAString= alib::AString;
 
/// This type is not used in the code. It is for testing whether \dxl finds members
/// which are inherited through a (chained!) type definition.
class TestAString : public ChainedAString {
  public:
    /// This tests if overridden members are still reached directly.
    /// @return A pointer to the buffer.
    const alib::character* Buffer() const  { return alib::AString::Buffer(); }
};
 
/// The possible exit codes of the application. In addition to these, the codes defined with
/// #"App::BuiltInExitCodes" and #"app::ExitCodes" might occur.
enum class ExitCodes {
    OK                          =  0, ///< All went well.
    CantOpenDoxyfile            = 20, ///< Doxygen INI-file (usually Doxyfile) not found.
    NoTagfileGeneratedByDoxyfile= 21, ///< Doxygen INI-file entry <b>GENERATE_TAGFILE</b> needs to
                                      ///< be set to enable DoxygenXLinks.
    OtherErrorInDoxyfile        = 22, ///< Some other error occurred when parsing the Doxygen
                                      ///<  INI-file.
    TagFileNotFound             = 23, ///< Doxygen tag-file not created, yet. Needs a second run.
    NoHTMLFilesFound            = 24, ///< HTML files to process not found.
    CantOpenHMLFile             = 25, ///< A HTML file was not found or could not be accessed.
    CantWriteHMLFile            = 26, ///< A HTML file that was read before, could not be written.
    NoSourceFilesFound          = 27, ///< No sources found with the specification given in the Doxyfile.
    CantOpenSrcFile             = 28, ///< A source file was not found or could not be accessed.
    NoSourceCopiesFound         = 29, ///< No sources found with the specification given in the Doxyfile.
    CantOpenReplSrcFile         = 30, ///< A replacement source file was not found or could not be accessed.
    CantWriteReplSrcFile        = 31, ///< A replacement source file was not found or could not be accessed.
};
 
/// TODO(251212 17:24): Ich glaube wirklich das kann man löschen und nur noch die
///                     app::App::Exceptions::ControlledEarlyExit werfen!
///                     Zuletzt zumindest alle durchgehen und schauen welche noch benutzt werden
enum class Exceptions {
    ErrorOpeningFile            =  1, ///< todox
    UnknownKind                 =  2, ///< todox
    XMLSyntaxError              = 10, ///< todox
    NotATagStart                = 11, ///< todox
    UnexpectedXMLTag            = 12, ///< todox
    XMLEndTagNotInSameLine      = 13, ///< todox
    FileNotOnRootLevel          = 14, ///< todox
    DuplicateChildName          = 15, ///< todox
    DuplicateCompound           = 16, ///< todox
    UnexpectedXMLValue          = 17, ///< todox
};
 
// #################################################################################################
/// class DoxygenXLinks
// #################################################################################################
/// This is the main class of this little project that organizes the pieces and performs
/// all necessary steps. Method #Run is called in #"App::States::Run"
class DoxygenXLinks  {
    friend void DbgUnitTests(DoxygenXLinks*);
 
  protected:
    /// The file tree used for reading the source files.
    alib::SharedFTree                     fTreeSources;
 
    /// The file tree used for reading the html files.
    alib::SharedFTree                     fTreeHTML;
 
    /// Used to optimize logging speed in critical code section.
    alib::Verbosity                       verbosityGetELDecoration = alib::Verbosity(-1);
 
  public:
    /// The thread pool used to load and search the HMTL files.
    DXLThreadPool                         TPool;
 
    /// The lock used with the allocator #MA. Locking needs only be performed while the
    /// threadpool is active.
    alib::Lock                             DLLock;
 
    /// Our mono allocator.
    alib::MonoAllocator                    MA;
 
    /// The Doxyfile to process.
    DoxygenINIFile                         Doxyfile;
 
    /// The set of unique \xls found in the source and HTML files.
    alib::HashMap< alib::MonoAllocator, alib::String, XLink*,
                   std::hash<alib::String>, std::equal_to<alib::String>,
                   alib::lang::Caching::Enabled,alib::Recycling::None>     XLinkMap;
 
    /// Some statistical data displayed with verbose output option. (todo!)
    struct Statistics {
        /// The number of unique XLinks found in HTML files.
        std::atomic<int> UniqueXLinks    = 0;
 
        /// The number of unresolved XLinks.
        std::atomic<int> UnresolvedXLinks    = 0;
 
        /// The number of ambiguous XLinks.
        std::atomic<int> AmbiguousXLinks    = 0;
 
        /// The number of XLinks that have an erroneous specification.
        std::atomic<int> XLinksWithErrors = 0;
 
        /// The number of unresolved XLinks.
        std::atomic<int> XLinksWithWarnings = 0;
 
        /// The number of HTML files
        std::atomic<int> HTMLFiles    = 0;
 
        /// The number of HTML file lines
        std::atomic<int> HTMLFileLines    = 0;
 
        /// The cumulated size of the HTML file lines
        std::atomic<int> HTMLFileSize    = 0;
 
        /// The number of attributed EL-anchors.
        std::atomic<int> ELReplacements    = 0;
 
        /// The number of unresolved EL-anchors.
        std::atomic<int> ELReplacementsUnresolved    = 0;
 
        /// The number of attributed ELREF-anchors.
        std::atomic<int> ELREFReplacements    = 0;
 
        /// The number of unresolved ELREF-anchors.
        std::atomic<int> ELREFReplacementsUnresolved    = 0;
 
 
        /// The number of source files
        std::atomic<int> SourceFiles  = 0;
 
        /// The number of code lines read.
        std::atomic<int> SourceFileLines  = 0;
 
        /// The cumulated size of the source files
        std::atomic<int> SourceFileSize    = 0;
 
        /// Duration of reading and writing HTML files.
        alib::Ticks::Duration  TimeHTMLReplacements;
 
        /// Duration of reading tag-files and sources.
        alib::Ticks::Duration  TimeIndexAndSourceLoading;
 
        /// The number of replaced source files
        std::atomic<int> ReplSourceFiles  = 0;
 
        /// The number of code lines read in the replacement source tree.
        std::atomic<int> ReplSourceFileLines  = 0;
 
        /// The cumulated size of the replaced source files
        std::atomic<int> ReplSourceFileSize    = 0;
 
        /// Duration of reading and writing the restorable source copies.
        alib::Ticks::Duration  TimeSourceReplacements;
 
 
};
 
    /// Statistics collected during the execution and printed when verbose output is requested.
    Statistics Stats;
 
    /// An exclamation file, containing locations in in HTML-files. In rare cases \dxl might
    /// see an \xl that is not one. Such cases have to be entered in the external exclamation file.
    ExclamationFile     Exclamations;
 
    /// The path to this file. Todo: make configurable and auto-generated from app-name
    alib::CString       ExclamationsPath = "DoxygenXLinks.exclamations.txt";
 
    /// The vector of #Index objects resulting from doxygen tag-files. (One \b %Index per
    /// tag-file.)
    alib::StdVectorMA<Index*>       Indices;
 
 
protected:
    /// Implements a special feature: Files not found in doxygen tag-files, might still have
    /// an HTML-file containing its source. Such files are named \c "XYZ_source.html".
    /// This method is called if an \xl to a file cannon not be resolved otherwise.
    /// @param xLink The \xl with the unresolved target file.
    void tryResolveHTMLTargetFile(XLink& xLink);
 
    /// Scans the source files input. This is mainly needed to add "clickable" output on
    /// erroneous links. But over time, more features started depending on the availability
    /// of the sources.
    void scanSrcFiles();
 
    /// Launches the #"SourceLocationFinder" jobs on the #".fTreeSources;source-file tree".
    void scheduleSrcScanners();
 
    /// Scans the HTML input file tree.
    void scanHTMLFiles();
 
    /// Launches the #"HTMLReplacer" jobs on the #".fTreeHTML;HTML-file tree".
    void schduleHTMLReplacers();
 
    /// Scans the replacement-source folders.
    /// @param folder The directory to search copies of sources.
    void scanReplSrcFiles(const alib::String& folder);
 
    /// Launches the #"SourceReplacer" jobs on the #".fTreeSources;source-file tree".
    /// @param folder The directory to search copies of sources. (Only used for log-output here.)
    void schduleSourceReplacers(const alib::String& folder);
 
    /// Writes the non-resolved and ambiguous src links in an ordered fashion.
    void writeErrors();
 
    /// Writes links found in sources which were not found in the HTML files.
    /// This might happen if doxygen was not run properly.
    void writeXLinksInSourceNotInHTML();
 
    /// This should not write any output. If so, it indicates that the source and html parsers
    /// detect different link contents.
    void writeXLinksInHTMLNotInSource();
 
    /// Writes some statistics. If \p{verbose} is off, then just one line with the number of
    /// links in each category is given.
    /// Reads #"var Variable" <b>STATISTICS</b>
    void writeStatistics();
 
    ///  Writes all links that are filtered by the given expression.
    /// @param expressionString The filter expression.
    /// @param format           The output format.
    void listLinks(const alib::String& expressionString, const alib::String& format);
 
public:
    /// Constructor.
    DoxygenXLinks();
 
    /// Virtual destructor.
    ~DoxygenXLinks();
 
    // #############################################################################################
    // Interface
    // #############################################################################################
    /// The main method of this main class of project \dxl.
    void Run();
 
    /// This method stores a link in the %XLinkMap but does not resolve it, yet.
    /// It is called by the #"SourceLocationFinder".
    /// @param searchString The string found in the HTML file to search for.
    /// @return The \xl object.
    XLink*      RegisterXLink(alib::String& searchString);
 
    /// This is the central search method of this project, called by the class #"HTMLReplacer".
    /// While most of the search-logic is located in the method #"Index::Search",
    /// this method is responsible for the creation of creating and hashing \xl objects and
    /// for collecting erroneous links.
    /// @param searchString The string found in the HTML file to search for.
    /// @param htmlFile     The HTML file where this link is currently found.
    ///                     This is used to resolve #"XLink::NextLocal;local versions".
    /// @return The \xl object. If its method #"link IsResolved" returns \c false,
    ///         no target information is set, and no replacement must happen by the caller.
    XLink*      GetXLink(alib::String& searchString, const alib::files::File& htmlFile);
 
    /// This is used with HTML-links that are set by \b Doxygen automatically (not explicitly
    /// by the documentation writer). It is determined which css classes are added to the anchor.
    /// @param styles         The target styles struct to set.
    /// @param isELREFAnchor  Denotes whether an anchor with class "el" or "elref" was found.
    /// @param elLocation     The HTML-file where the EL-anchor was found.
    /// @param targetFilename The target HTML-file name portion of the anchor.
    /// @param targetAnchor   The anchor portion of anchor.
    /// @param lineNo         The line in \p{elLocation}. (Used for log-output.)
    /// @param colNo          The column in \p{elLocation}. (Used for log-output.)
    void        GetELDecoration( Styles&      styles,
                                 bool         isELREFAnchor,
                                 alib::File&  elLocation,
                                 alib::String targetFilename,
                                 alib::String targetAnchor,
                                 int lineNo, int colNo        );
 
 
    // #############################################################################################
    // Other Methods
    // #############################################################################################
    /// @return A reference the #"FTree" instance holding the sources.
    alib::FTree&       GetSourceTree() { return *fTreeSources; }
 
    /// @return The mutex assigned to the shared #"FTree".
    alib::SharedLock&  GetSourceTreeLock() { return fTreeSources.GetLock(); }
 
    /// @return A reference the #"FTree" instance holding the HTML-files .
    alib::FTree&       GetHTMLTree() { return *fTreeHTML; }
 
    /// @return The mutex assigned to the shared #"FTree" holding the HTML-files.
    alib::SharedLock&  GetHTMLTreeLock() { return fTreeHTML.GetLock(); }
    
    /// This method searches the anchor with the given name in all tag-files and adds the given
    /// title information.<br>
    /// One way to receive the title information is described in manual section...
    /// TODO: also ist das überhaupt noch drin? Jedenfalls funktionierte es ja mit den ALib-macro-groups gar nicht!
    ///
    /// Note that all given strings are volatile and must be copied before stored.
    /// @param anchorName   The name of the anchor to receive a title.
    /// @param anchorTitle  The title to set.
    /// @param sourceHint   Information about where the anchor title came from.
    void AddAnchorTitle( const alib::String& anchorName, const alib::String& anchorTitle,
                         const alib::String& sourceHint  );
}; // class DoxygenXLinks
 
/// Converts the following HTML-entities to ASCII-code characters in the given string \p{buffer}:
/// HTML Entity      | ASCII Character
/// -----------------|--------------------------
/// <c>\&lt;</c>     | <c>&lt;</c>
/// <c>\&gt;</c>     | <c>&gt;</c>
/// <c>\&amp;</c>    | <c>&amp;</c>
/// <c>\&apos;</c>   | <c>&apos;</c>
/// <c>\&lsqb;</c>   | <c>[</c>
/// <c>\&rsqb;</c>   | <c>]</c>
/// <c>\&commat;</c> | <c>\@</c>
/// <c>\&dollar;</c> | <c>$</c>
/// <c>\&nbsp;</c>   | <c>' '</c>
///
/// \note HTML entity <c>"\&quot;"</c> is \b kept in!
/// @see Function #ConvertASCIItoHTMLEntities which does the opposite.
/// @param buffer The buffer to search for HTML entities and convert them to ASCII.
void ConvertHTMLEntitiesToAscii(alib::AString& buffer);
 
/// The counter-function of #ConvertHTMLEntitiesToAscii.
/// Also converts quotes <c>'\"'</c> to HTML entity <c>"\&quot;"</c> (what the counter-function
/// does not do).
/// @param buffer The buffer to search for ASCII characters to be converted to HTML entities.
void ConvertASCIItoHTMLEntities(alib::AString& buffer);
 
}  //namespace [dxl]
 
ALIB_CAMP_ENUM( dxl::ExitCodes  , cli::ERExitCodeDecl     , APPCLI_CAMP , "DLExitCodes" )
ALIB_CAMP_ENUM( dxl::Exceptions , exceptions::ERException , APPCLI_CAMP , "E"   )
#endif // HPP_DOXYGEN_LINKER