expressions.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_EXPRESSIONS
#define HPP_DXL_EXPRESSIONS
#pragma once
#include "xlink.hpp"
#include "ALib.Expressions.H"
 
namespace alib::expressions { class Compiler; struct Expression;}
namespace dxl {
 
/// The expression scope used with \dxl expressions of options <c>--list</c> and <c>--format</c>.
/// Holds a pointer to the #"XLink" in question and its source string.
struct DXLScope : alib::expressions::Scope
{
    XLink*          Xlink;      ///<The link to evaluate.
 
    alib::String    Path;       ///< The path (either scope- or file path) of the target entity.
                                ///< Created once with identifier \b Path.
    /// Constructor.
    /// Sets the expression compiler singleton which is located in an anonymous namespace.
    DXLScope();
 
    /// Resets this scope to be read for the next evaluation.
    void Reset() override {
        Path= nullptr;
        Scope::Reset();
    }
 
};
 
/// The expression formatter used with \dxl expressions option <c>--format</c>.
/// The only difference to its parent class #"ExpressionFormatter" is that with construction
/// it grabs the expression compiler singleton which is located in an anonymous namespace.
struct DXLExpressionFormatter : alib::expressions::util::ExpressionFormatter {
    /// Constructor. Passes the internal compiler singleton to the parent class.
    /// @param formatString Passed to the constructor of #"ExpressionFormatter".
    DXLExpressionFormatter( const alib::String& formatString );
};
 
/// This class implements an #"alib_mod_expressions;ALib Expression Compiler Plugin"
/// (internally) and with that enables "run-time expressions" to be evaluated on #"XLink"s.
///
/// For quick samples, see manual chapter #"dxl_manual_addfeat_queries"
///
/// Such run-time expressions are evaluated when option <c>--list</c> is passed.
/// Here, an expression that evaluated to a boolean value has to be passed. (Integrals are also
/// accepted, they are compared to zero). If the result is \c true, the \xl will be printed on
/// the console together with a list of its source locations.
///
/// A second instance where expressions are evaluated are with the option <c>--format</c>.
/// By using an \alib #"ExpressionFormatter", python-style format strings with expressions in
/// its placeholder are processed per resulting \xl.
///
/// All identifier and function names are defined to be matched case-insensitive and can be
/// abbreviated along their <em>CamelHumps</em>. This means an identifier called
///
///     CamelHumpCounter
///
/// can be abbreviated to:
///
///     CamelHC
///     CHCounter
///     CamHuCo
///     CHC
///     chc
///     cHc
///
/// and so on.
///
/// # Implemented Expression Features #
///
/// # Types: #
/// <br>
/// This plug-in introduces the following types to the expression compiler:
/// - #"Target::Kind;2"
/// - #"Index::Node;2"
///
/// The type #"Target::Kind;2" is auto-cast to built-in expression type \b Integer to allow all
/// common operators, especially bitwise boolean operators.
///
/// # Constants: #
/// <br>
/// Type                      | Name              |Min. Abbreviation
/// --------------------------|-------------------|-----------------
/// #"Target::Dir;*"          |\b Dir            | dir
/// #"Target::File;*"         |\b File           | fil
/// #"Target::Page;*"         |\b Page           | page
/// #"Target::Group;*"        |\b Group          | g
/// #"Target::DocAnchor;*"    |\b DocAnchor      | da
/// #"Target::Namespace;*"    |\b NameSpace      | ns
/// #"Target::Struct;*"       |\b Struct         | stru
/// #"Target::Class;*"        |\b Class          | c
/// #"Target::Union;*"        |\b Union          | u
/// #"Target::Concept;*"      |\b ConCept        | cc
/// #"Target::Macro;*"        |\b Macro          | m
/// #"Target::Typedef;*"      |\b TypeDef        | td
/// #"Target::Variable;*"     |\b Variable       | v
/// #"Target::Function;*"     |\b Function       | f
/// #"Target::Enumeration;*"  |\b Enumeration    | e
/// #"Target::EnumElement;*"  |\b EnumValue      | ev
/// #"Target::GenericMember;*"|\b GenericMember  | gm
/// #"Target::RECORD;*"       |\b Record         | r
/// #"Target::UNSPECIFIED;*"  |\b UnSpecified    | us
///
/// <br>
/// # Functions: #
/// The following functions retrieve values concerning the parsed \xl, its resolved targets,
/// tag-files and so on. As common with run-time expressions, all functions implementations
/// duly suppress any error. For example, when a parent of a target is addressed that does not
/// exist, and this parent is passed to function <b>Name</b>, then, an emtpy string is silently
/// returned. Functions that return an integer value return \c -1 or \c 0 if erroneous parameters
/// are passed, dependent on whatever is more appropriate.
///
///
/// ## Functions Retrieving The Basic XLink Values: <br>
///
/// Return Type          | Name                | Min. Abbrev. | Signature  | Description
/// ---------------------|---------------------------| -----|--------------|--------------
/// String               | \b LinkString             | ls   | \e void      | Returns the original link string.
/// String               | \b LinkTarget             | lt   | \e void      | Returns the \xl string excluding the display specification. (In other words: The link string up to the semicolon <c>';'</c>.)
/// String               | \b LinkDisplay            | ld   | \e void      | Returns the display as specified in the \xl. \note The resolved display text is received with function <b>Display</b>.
/// #"Target::Kind"      | \b KindSpec               | ks   | \e void      | Returns the character (as a String) that was given in the link-string to specify the target kind with optional prefix <c>[!tspec]</c>. See manual chapter #"dxl_xl_target_kinds")
/// Integer              | \b CountScopeHints        | csh  | \e void      | Returns the number of scopes-hints provided with the link string.
/// String               | \b ScopeHint              | sh   | Integer      | Returns the name of the n-th parent scope, as specified in the link string.
/// String               | \b CountScope             | cs   | \e void      | Returns the number of scopes provided with the link string.
/// String               | \b Scope                  | s    | Integer      | Returns the name of the n-th parent scope, as specified in the link string.
/// String               | \b Identifier             | i    | \e void      | Returns the identifier name as specified in the link string.
/// Boolean              | \b IsResolved             | ir   | \e void      | Returns whether the \xl is uniquely resolved.
/// Integer              | \b CountParaMS            | cpm  | \e void      | Receives the number of function-parameters given with the \xl.
/// String               | \b ParaMeterS             | pm   | \e void      | Receives the function-parameters given with the \xl.
/// Integer              | \b CountTemplateParaMS    | ctpm | \e void      | Receives the number of template-parameters given with the \xl.
/// String               | \b TemplateParaMS         | tpm  | \e void      | Receives the template-parameters given with the \xl.
/// Integer              | \b CountTemplateSpecParaMS| ctspm| \e void      | Receives the number of template-specialization-parameters given with the \xl.
/// String               | \b TemplateSpecParaMS     | tspm | \e void      | Receives the template-specialization-parameters given with the \xl.
/// Integer              | \b ErrorCode              | ec   | \e void      | Returns the #"XLink::Errors;error- and warning code" of the \xl.
/// Boolean              | \b HasError               | he   | \e void      | Returns whether an error occurred during the \xl assembly.
/// Boolean              | \b HasWarning             | hw   | \e void      | Returns whether a warning was encountered during the \xl assembly.
/// Boolean              | \b IsGood                 | ig   | \e void      | Returns whether the \xl is uniquely resolved and no warnings or errors have been found.
/// Boolean              | \b IsScannedHtmlFile      | ishf | \e void      | Returns \c true if the link targets an HTML file that was not received from the tag-file, but scanned in \b Doxygen's output-folder. See manual section #"dxl_xl_file").
/// Boolean              | \b IsIndirectSourceFile   | iihf | \e void      | Returns \c true if the link targets the source code of a file directly, which then also targets an HTML-file scanned in \b Doxygen's output-folder. See manual section #"dxl_xl_file").
/// Boolean              | \b IsInherited            | ii   | \e void      | Returns \c true if the link targets a member of a base type, while the derived type is given as its scope. See manual section #"dxl_xl_indirect").
/// Boolean              | \b IsIndirectTypeDefMember| iitdm| \e void      | Returns \c true if the link targets a member of an underlying type of a type definition. See manual section #"dxl_xl_indirect").
/// Boolean              | \b IsIndirectTypeDef      | iitd | \e void      | Returns \c true if the link targets the underlying type of a type definition. See manual section #"dxl_xl_typedefinitions").
/// String               | \b Display                | d    | \e void      | Returns the assembled display string.
///
///
/// ## Functions On The Resolved Target Node: <br>
/// Return Type          | Name                  | Min. Abbrev. | Signature  | Description
/// ---------------------|---------------------------| -----|--------------|--------------
/// Index::Node        | \b %Target                | t    | \e void      | Returns the #"Index::Node" of the target-entity.
/// #"Target::Kind"      | \b Kind                   | k    | \e void      | Returns the kind of the resolved target entity.
/// Integer              | \b Depth                  | dep  | \e void      | Returns the depth of the target node. With source entities this is the scope-depth, with folders and files, the depth in the filesystem- as far as doxygen is told to consider the parents.
/// String               | \b Name                   | n    | \e void      | Returns the name of the target entity.
/// String               | \b Name                   | n    | Index::Node| Returns the name of the given cursor.
/// Index::Node        | \b Parent                 | p    | \e void      | Returns the parent of the target-entity.
/// Index::Node        | \b Parent                 | p    | Index::Node| Returns the parent of the given cursor.
/// Index::Node        | \b Parent                 | p    | Integer      | Returns the n-th parent of the target-entity.
/// String               | \b Path                   | path | \e void      | Returns the path-string of the target-entity. With files and folders <c>'/'</c> is used as the separation character, with code-entities <c>"::"</c> is used.
/// String               | \b Path                   | path | Index::Node| Returns the path-string of the given cursor. (Pass "Target", like in: <em>"Path(Target)"</em> or <em>"Path(Parent(Target))"</em>.)
/// Integer              | \b CountParaMS            | cpm  | Index::Node| Receives the number of function-parameters of the target node. (Pass "Target", like in: <em>"CParams(Target)"</em>.)
/// String               | \b ParaMeterS             | pm   | Index::Node| Receives the function-parameters of the target node. (Pass "Target", like in: <em>"Params(Target)"</em>.)
/// Integer              | \b CountTemplateParaMS    | ctpm | Index::Node| Receives the number of template-parameters of the target node. (Pass "Target", like in: <em>"CTParms(Target)"</em>.)
/// String               | \b TemplateParaMS         | tpm  | Index::Node| Receives the template-parameters of the target node. (Pass "Target", like in: <em>"TParams(Target)"</em>.)
/// Integer              | \b CountTemplateSpecParaMS| ctspm| Index::Node| Receives the number of template-specialization-parameters of the target node. (Pass "Target", like in: <em>"CTSParams(Target)"</em>.)
/// String               | \b TemplateSpecParaMS     | tspm | Index::Node| Receives the template-specialization-parameters of the target node. (Pass "Target", like in: <em>"TSParams(Target)"</em>.)
///
/// ## Functions Concerning Source-, HTML- and Tag-Files: <br>
/// Return Type          | Name                  | Min. Abbrev. | Signature  | Description
/// ---------------------|---------------------------| -----|--------------|--------------
/// Integer              | \b CountSourceLocationS   | csl | \e void      | Receives the number of source-locations that a \xl was found at. \note Two \xls in sources are different if their source string is different - even if they resolve to the same target.
/// Integer              | \b CountHtmlLocationS     | chl | \e void      | Receives the number of (replaced) HTML-locations that a \xl was found at. \note This number is often higher than the number of source-locations, because \b Doxygen places the same documentation text (which includes the \xl!) in different areas.
/// String               | \b TagFilePath            | tfp | \e void      | Receives the path of the tag file that defined the resolved target.
/// String               | \b TagFilePath            | tfp | Index::Node| Receives the path of the tag file that defined the given node.
/// String               | \b TagFileName            | tfn | \e void      | Receives the file-portion of the path of the tag file that defined the resolved target.
/// String               | \b TagFileName            | tfn | Index::Node| Receives the file-portion of the path of the tag file that defined the given node.
/// Integer              | \b TagFileLine            | tfl | \e void      | Receives the line number in the tag file that defined the resolved target.
/// Integer              | \b TagFileLine            | tfl | Index::Node| Receives the line number in the tag file that defined the given node.
/// String               | \b HtmlFile               | hf  | \e void      | Receives the name of the HTML-file that documents the target.
/// String               | \b HtmlFile               | hf  | Index::Node| Receives the name of the HTML-file that documents the given node.
/// String               | \b HtmlAnchor             | ha  | \e void      | Receives the anchor within the HTML-file that documents the target. (Not all entities have an anchor. For example namespace, classes, do not have one, because they have an own dedicated page.)
/// String               | \b HtmlAnchor             | ha  | Index::Node| Receives the anchor within the HTML-file that documents the given node.
///
class DXLExpression
{
  protected:
    DXLScope*                        scope;        ///< The scope used with this filter.
    alib::expressions::Expression    expression;   ///< The compiled expression.
 
  public:
    /// Constructor. Compiles the given expression.
    /// @param expressionString The expression string.
    DXLExpression(const alib::String& expressionString );
 
    /// Destructor.
    ~DXLExpression();
 
    /// @return The expression string given with construction (in a normalized fashion!).
    alib::String GetExpressionString() { return expression->GetNormalizedString(); }
 
    /// @return The expression string after all optimizations have been performed.
    alib::String GetOptimizedString() { return expression->GetOptimizedString(); }
 
    /// @return The result-type of the expression - as a \b Box: that's how \alib_expressions
    ///         represents types!
    alib::Box  ResultType() { return expression->ResultType(); }
 
    /// @return \c true if the expression evaluates to a constant value (the same result for
    ///            any \xl), \c false otherwise.
    alib::Box  IsConstant() { return expression->IsConstant(); }
 
    /// The filter method.
    /// @param xLink        The link to evaluate.
    /// @return The result of the expression when evaluated with the scope of the given \b XLink
    ///         and its search string.
    bool Includes( XLink* xLink );
};
 
}  // namespace [dxl]
 
#endif // HPP_DXL_EXPRESSIONS