exclamations.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_EXCLAMATIONS
#define HPP_DXL_EXCLAMATIONS
#pragma once
#include "ALib.Strings.H"
#include "ALib.Containers.List.H"
#include "ALib.Monomem.StdContainers.H"
#include "ALib.System.H"
 
namespace dxl {
 
/// Reads a text file with exclamation definitions. Entries have the format
///    filename, line [, col]
/// Method Includes tests a source location for beeing excluded.
struct ExclamationFile {
 
    /// An entry of the exclamation file.
    class Entry {
      friend struct ExclamationFile;
        
      protected:
        /// The path or a portion of it of the HTML file that the exclamation is defined for.
        alib::String128     FilePath;
 
        /// The line number in #FilePath of the exclamation.
        int                 Line;
 
        /// The column in #Line in #FilePath of the exclamation.
        int                 Column;
 
        /// The line number in #FilePath that this entry was defined at.
        int                 DefinitionLine; ///< The line number of the exclamation file.
 
        /// Is set when this entry was used. When the program exits, all entries that have not
        /// been hit are displayed.
        bool               Used;
 
      public:
        /// Constructs an entry.
        /// @param filePath         Assigned to the field member #FilePath.
        /// @param line             Assigned to the field member #Line.
        /// @param column           Assigned to the field member #Column.
        /// @param definitionLine   Assigned to the field member #DefinitionLine.
        Entry(alib::String filePath, int line, int column, int definitionLine)
        : FilePath{filePath}, Line{line}, Column{column}, DefinitionLine{definitionLine}
        , Used{false}                                                                             {}
 
        /// Tests if the given pair of \p{line} and \p{colum} are equal to what is defined with
        /// this rule.
        /// @param line   The line to test.
        /// @param column The colum to test.
        /// @return \c true if this exclamation denotes the given position, \c false otherwise.
        bool Matches(int line, int column ) {
            if ( Line == line &&  column == Column) {
                Used= true;
                return true;
            }
            return false;
        }
    };
 
    /// A simple linear list of entries.
    alib::ListMA<Entry>        List;    // todo: make forward list?
 
    /// Constructor
    ExclamationFile()
    : List{alib::monomem::GLOBAL_ALLOCATOR}                                  {}
 
    /// Reads an exclamation file.
    /// @param filePath The path to the file to read.
    void Read(const alib::CString& filePath);
 
 
    /// Collects all rules to a given filePath in the given \p{result} vector.
    /// @param filePath todox
    /// @param result   Filled with all rules defined for the file specified by \p{filePath}.
    void Get(const alib::system::PathString& filePath, alib::StdVectorMA<Entry*>& result);
};
 
 
} //namespace [dxl]
 
 
#endif // HPP_DXL_EXCLAMATIONS