Description:

This class implements an ALib Expression Compiler Plugin (internally) and with that enables "run-time expressions" to be evaluated on XLinks.

For quick samples, see manual chapter 4.2 Runtime Expression Language

Such run-time expressions are evaluated when option –list 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 true, the XLink 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 –format. By using an ALib ExpressionFormatter, python-style format strings with expressions in its placeholder are processed per resulting XLink.

All identifier and function names are defined to be matched case-insensitive and can be abbreviated along their CamelHumps. This means an identifier called

CamelHumpCounter

can be abbreviated to:

CamelHC
CHCounter
CamHuCo
CHC
chc
cHc

and so on.

Implemented Expression Features

Types:

This plug-in introduces the following types to the expression compiler:

The type Target::Kind is auto-cast to built-in expression type Integer to allow all common operators, especially bitwise boolean operators.

Constants:

Type	Name	Min. Abbreviation
Dir	Dir	dir
File	File	fil
Page	Page	page
Group	Group	g
DocAnchor	DocAnchor	da
Namespace	NameSpace	ns
Struct	Struct	stru
Class	Class	c
Union	Union	u
Concept	ConCept	cc
Macro	Macro	m
Typedef	TypeDef	td
Variable	Variable	v
Function	Function	f
Enumeration	Enumeration	e
EnumElement	EnumValue	ev
GenericMember	GenericMember	gm
RECORD	Record	r
UNSPECIFIED	UnSpecified	us

Functions:

The following functions retrieve values concerning the parsed XLink, 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 Name, then, an emtpy string is silently returned. Functions that return an integer value return -1 or 0 if erroneous parameters are passed, dependent on whatever is more appropriate.

Functions Retrieving The Basic XLink Values:

Return Type	Name	Min. Abbrev.	Signature	Description
String	LinkString	ls	void	Returns the original link string.
String	LinkTarget	lt	void	Returns the XLink string excluding the display specification. (In other words: The link string up to the semicolon `';'`.)
String	LinkDisplay	ld	void	Returns the display as specified in the XLink. Note The resolved display text is received with function Display.
Kind	KindSpec	ks	void	Returns the character (as a String) that was given in the link-string to specify the target kind with optional prefix `[!tspec]`. See manual chapter 3.3.3 Disambiguating By Target Kind")
Integer	CountScopeHints	csh	void	Returns the number of scopes-hints provided with the link string.
String	ScopeHint	sh	Integer	Returns the name of the n-th parent scope, as specified in the link string.
String	CountScope	cs	void	Returns the number of scopes provided with the link string.
String	Scope	s	Integer	Returns the name of the n-th parent scope, as specified in the link string.
String	Identifier	i	void	Returns the identifier name as specified in the link string.
Boolean	IsResolved	ir	void	Returns whether the XLink is uniquely resolved.
Integer	CountParaMS	cpm	void	Receives the number of function-parameters given with the XLink.
String	ParaMeterS	pm	void	Receives the function-parameters given with the XLink.
Integer	CountTemplateParaMS	ctpm	void	Receives the number of template-parameters given with the XLink.
String	TemplateParaMS	tpm	void	Receives the template-parameters given with the XLink.
Integer	CountTemplateSpecParaMS	ctspm	void	Receives the number of template-specialization-parameters given with the XLink.
String	TemplateSpecParaMS	tspm	void	Receives the template-specialization-parameters given with the XLink.
Integer	ErrorCode	ec	void	Returns the error- and warning code of the XLink.
Boolean	HasError	he	void	Returns whether an error occurred during the XLink assembly.
Boolean	HasWarning	hw	void	Returns whether a warning was encountered during the XLink assembly.
Boolean	IsGood	ig	void	Returns whether the XLink is uniquely resolved and no warnings or errors have been found.
Boolean	IsScannedHtmlFile	ishf	void	Returns `true` if the link targets an HTML file that was not received from the tag-file, but scanned in Doxygen's output-folder. See manual section 3.8 Linking To Files And Folders).
Boolean	IsIndirectSourceFile	iihf	void	Returns `true` if the link targets the source code of a file directly, which then also targets an HTML-file scanned in Doxygen's output-folder. See manual section 3.8 Linking To Files And Folders).
Boolean	IsInherited	ii	void	Returns `true` if the link targets a member of a base type, while the derived type is given as its scope. See manual section 3.9 Indirect Linking: Inherited Members And Those Of Underlying Types).
Boolean	IsIndirectTypeDefMember	iitdm	void	Returns `true` if the link targets a member of an underlying type of a type definition. See manual section 3.9 Indirect Linking: Inherited Members And Those Of Underlying Types).
Boolean	IsIndirectTypeDef	iitd	void	Returns `true` if the link targets the underlying type of a type definition. See manual section 3.10 Targeting Underlying Types of Type-Definitions).
String	Display	d	void	Returns the assembled display string.

Functions On The Resolved Target Node:

Return Type	Name	Min. Abbrev.	Signature	Description
Index::Node	Target	t	void	Returns the Node of the target-entity.
Kind	Kind	k	void	Returns the kind of the resolved target entity.
Integer	Depth	dep	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	Name	n	void	Returns the name of the target entity.
String	Name	n	Index::Node	Returns the name of the given cursor.
Index::Node	Parent	p	void	Returns the parent of the target-entity.
Index::Node	Parent	p	Index::Node	Returns the parent of the given cursor.
Index::Node	Parent	p	Integer	Returns the n-th parent of the target-entity.
String	Path	path	void	Returns the path-string of the target-entity. With files and folders `'/'` is used as the separation character, with code-entities `"::"` is used.
String	Path	path	Index::Node	Returns the path-string of the given cursor. (Pass "Target", like in: "Path(Target)" or "Path(Parent(Target))".)
Integer	CountParaMS	cpm	Index::Node	Receives the number of function-parameters of the target node. (Pass "Target", like in: "CParams(Target)".)
String	ParaMeterS	pm	Index::Node	Receives the function-parameters of the target node. (Pass "Target", like in: "Params(Target)".)
Integer	CountTemplateParaMS	ctpm	Index::Node	Receives the number of template-parameters of the target node. (Pass "Target", like in: "CTParms(Target)".)
String	TemplateParaMS	tpm	Index::Node	Receives the template-parameters of the target node. (Pass "Target", like in: "TParams(Target)".)
Integer	CountTemplateSpecParaMS	ctspm	Index::Node	Receives the number of template-specialization-parameters of the target node. (Pass "Target", like in: "CTSParams(Target)".)
String	TemplateSpecParaMS	tspm	Index::Node	Receives the template-specialization-parameters of the target node. (Pass "Target", like in: "TSParams(Target)".)

Functions Concerning Source-, HTML- and Tag-Files:

Return Type	Name	Min. Abbrev.	Signature	Description
Integer	CountSourceLocationS	csl	void	Receives the number of source-locations that a XLink was found at. Note Two XLinks in sources are different if their source string is different - even if they resolve to the same target.
Integer	CountHtmlLocationS	chl	void	Receives the number of (replaced) HTML-locations that a XLink was found at. Note This number is often higher than the number of source-locations, because Doxygen places the same documentation text (which includes the XLink!) in different areas.
String	TagFilePath	tfp	void	Receives the path of the tag file that defined the resolved target.
String	TagFilePath	tfp	Index::Node	Receives the path of the tag file that defined the given node.
String	TagFileName	tfn	void	Receives the file-portion of the path of the tag file that defined the resolved target.
String	TagFileName	tfn	Index::Node	Receives the file-portion of the path of the tag file that defined the given node.
Integer	TagFileLine	tfl	void	Receives the line number in the tag file that defined the resolved target.
Integer	TagFileLine	tfl	Index::Node	Receives the line number in the tag file that defined the given node.
String	HtmlFile	hf	void	Receives the name of the HTML-file that documents the target.
String	HtmlFile	hf	Index::Node	Receives the name of the HTML-file that documents the given node.
String	HtmlAnchor	ha	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	HtmlAnchor	ha	Index::Node	Receives the anchor within the HTML-file that documents the given node.

Definition at line 190 of file expressions.hpp.

#include <expressions.hpp>

Public Method Index:
	DXLExpression (const alib::String &expressionString)
	~DXLExpression ()
	Destructor.
alib::String	GetExpressionString ()
alib::String	GetOptimizedString ()
bool	Includes (XLink *xLink)
alib::Box	IsConstant ()
alib::Box	ResultType ()

Protected Field Index:
alib::expressions::Expression	expression
	The compiled expression.
DXLScope *	scope
	The scope used with this filter.

Field Details:

◆ expression

alib::expressions::Expression dxl::DXLExpression::expression

protected

The compiled expression.

Definition at line 194 of file expressions.hpp.

◆ scope

DXLScope* dxl::DXLExpression::scope

protected

The scope used with this filter.

Definition at line 193 of file expressions.hpp.

Constructor(s) / Destructor Details:

◆ DXLExpression()

dxl::DXLExpression::DXLExpression ( const alib::String & expressionString )

Constructor. Compiles the given expression.

Parameters

expressionString The expression string.

Definition at line 501 of file expressions.cpp.

◆ ~DXLExpression()

dxl::DXLExpression::~DXLExpression ( )

Destructor.

Definition at line 517 of file expressions.cpp.

Method Details:

◆ GetExpressionString()

alib::String dxl::DXLExpression::GetExpressionString ( )

inline

Returns: The expression string given with construction (in a normalized fashion!).

Definition at line 205 of file expressions.hpp.

◆ GetOptimizedString()

alib::String dxl::DXLExpression::GetOptimizedString ( )

inline

Returns: The expression string after all optimizations have been performed.

Definition at line 208 of file expressions.hpp.

◆ Includes()

bool dxl::DXLExpression::Includes ( XLink * xLink )

The filter method.

Parameters

xLink The link to evaluate.

Returns: The result of the expression when evaluated with the scope of the given XLink and its search string.

Definition at line 523 of file expressions.cpp.

◆ IsConstant()

alib::Box dxl::DXLExpression::IsConstant ( )

inline

Returns: true if the expression evaluates to a constant value (the same result for any XLink), false otherwise.

Definition at line 216 of file expressions.hpp.

◆ ResultType()

alib::Box dxl::DXLExpression::ResultType ( )

inline

Returns: The result-type of the expression - as a Box: that's how ALib Expressions represents types!

Definition at line 212 of file expressions.hpp.

The documentation for this class was generated from the following files:

Description:

Implemented Expression Features

Types:

Constants:

Functions:

Functions Retrieving The Basic XLink Values:

Functions On The Resolved Target Node:

Functions Concerning Source-, HTML- and Tag-Files:

Public Method Index:

Protected Field Index:

Field Details:

◆ expression

◆ scope

Constructor(s) / Destructor Details:

◆ DXLExpression()

◆ ~DXLExpression()

Method Details:

◆ GetExpressionString()

◆ GetOptimizedString()

◆ Includes()

◆ IsConstant()

◆ ResultType()