Description:

Encapsulates the information given with the links that this whole project was created for. Instances represent an XLink to a doxygen Target as given by the user.

Definition at line 46 of file xlink.hpp.

#include <xlink.hpp>

Public Type Index:
enum class	Errors { OK = 0 , TooManyParentsRequested = 1 , AnchorHasNoTitle = 2 , InappropriateDisplayTweak = 3 , WARNINGMARKER = 4 , Empty = 5 , NoTargetNameGiven = 6 , TooManyScopeHints = 7 , ScopeTooDeep = 8 , UnknownUnderlyingType = 9 , IllegalTargetKind =10 , LocalLinkWithScopeHints =11 , RestoringAmbiguousLocalLink = 12 , RestoringUnusedLocalLink = 13 }
	Possible results when parsing source links. More...

Public Static Field Index:
static constexpr int	MAX_SCOPE_DEPTH = 20
	The maximum number of scope hints and parents.

Public Static Method Index:
static Index::Node	ResolveTypeDef (const Index::Node &startCursor, const alib::String &origSearchString)

Public Field Index:
Target::FunctionArguments *	Args = nullptr
	Function arguments provided with the source XLink.
alib::ListMA< Index::Node > *	BaseTypes = nullptr
Styles	CSSClasses
alib::StdVectorMA< Index::Node >	DidYouMeanFunctionOverload
alib::StdVectorMA< Index::Node >	DidYouMeanNotATemplate
	A list of entries that are not templates, while a template type was searched.
alib::StdVectorMA< Index::Node >	DidYouMeanSameName
	A list of target nodes with the same name.
alib::StdVectorMA< Index::Node >	DidYouMeanSpecializations
Index::Node	DidYouMeanTemplateType
alib::StdVectorMA< Index::Node >	DidYouMeanVariable
	A list of entries that are variables, while the XLink's subscript does not match.
alib::String	Display = nullptr
alib::integer	DisplayOriginalPos = 0
Errors	Error = Errors::OK
	Possible errors that occured during parsing the search string given by the user.
alib::files::FTree::ConstCursorHandle	HTMLFileOfLocalLink = 0
	The tree node of the HTML file which created this copy of the originally given local XLink.
alib::StdVectorMA< Location >	HTMLLocations
bool	IsLocal = false
bool	IsUnderlyingTypeDef = false
Target::Kinds	KindSpec = Target::UNSPECIFIED
	Function arguments provided with the source XLink.
alib::String	LinkString
	The original source string.
XLink *	linkToParentScope = nullptr
Index::ConstCursorHandle	LocalLinkEntity = 0
alib::Lock	Lock
	The lock protecting the creation phase and as well allocator access.
alib::MonoAllocator	MA
	The mono allocator used to create the members of the class.
XLink *	NextLocal = nullptr
bool	NoIndirectionWarning = false
bool	NotFoundInHTML = false
	This flag is set when the specified link identifier was not found in the HTML files.
alib::String	Qualifiers = nullptr
	Function qualifiers like `const`, or `nothrow` provided with the source XLink.
alib::StdVectorMA< Location >	SourceLocations
Target::TemplateArguments *	SpecializationArgs = nullptr
alib::String	Subscript = nullptr
	A variable subscript provided by the source XLink.
alib::StdVectorMA< Index::SearchResult >	Targets
Target::TemplateArguments *	TemplateArgs = nullptr
alib::ListMA< Index::Node > *	TypeDefinitionTargets = nullptr
bool	WasPrinted = false

Public Method Index:
	XLink ()
	Constructor. Parses the given searchString and allocates the fields in the ma.
void	AssembleDisplay ()
int	CountLocalCopies ()
void	DbgReset ()
	This method is need for the unit-tests and available only with debug-compilations.
void	findInherited (const decltype(TGTRecord::BaseTypes)&bases)
XLink *	GetLinkToParent ()
std::pair< XLink *, bool >	GetLocalCopy (const alib::files::File &htmlFile)
bool	HasErrors () const
bool	HasWarnings (bool ignoreIndirects)
const alib::String &	Hint (int n) const
int	HintsSize () const
bool	IsGood (bool ignoreIndirects)
bool	IsParsed () const
bool	IsResolved () const
alib::String &	Name () const
void	Parse ()
	Parses the given searchString and allocates the fields in the MA.
void	PrintError (alib::Paragraphs &out, const alib::String &linkString, bool suppressHints=false)
Index::SearchResult &	Result ()
const Index::SearchResult &	Result () const
const alib::String &	Scope (int n) const
int	ScopeSize () const

Protected Field Index:
alib::String *	scope
int	scopeHintsSize
	The number of strings in the array scope that are only hints.
int	scopeSize = 0

Enumeration Details:

◆ Errors

enum class dxl::XLink::Errors

strong

Possible results when parsing source links.

Enumerator
OK	No error or warning.
TooManyParentsRequested	Warning: The display requested more parents to include than available.
AnchorHasNoTitle	Warning: An anchor without a title was used without providing a user-defined display string. DoxygenXLinks inserts the anchor name in this case.
InappropriateDisplayTweak	A display tweak was given that is not applicable to the resolved target type.
WARNINGMARKER	This is a marker-element that separates warnings from Errors.
Empty	The search string was empty (apart from possible whitespaces).
NoTargetNameGiven	No target identifier was given.
TooManyScopeHints	Too many scope-hints (words separated with spaces) were given.
ScopeTooDeep	The number of nested scope (namespaces/compounds) is too huge.
UnknownUnderlyingType	The underlying type requested with '^' was not found.
IllegalTargetKind	The target kind specification must be "!k " with k being a valid kind identification-character and a space following.
LocalLinkWithScopeHints	A local XLink (aka the identifier section starts with `'`.') must not have scope hints.
RestoringAmbiguousLocalLink	This error is set, with the command line option `–doxyfy`. As explained in the chapter 4.1 Doxyfication: Restoring Sources to \ref Commands, certain local links cannot be restored back to Doxygen's `\ref` command if they occur in different HTML files.
RestoringUnusedLocalLink	This error is set, with the command line option `–doxyfy`. It occurs when a local link 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.

Definition at line 57 of file xlink.hpp.

Field Details:

◆ Args

Target::FunctionArguments* dxl::XLink::Args = nullptr

Function arguments provided with the source XLink.

Definition at line 125 of file xlink.hpp.

◆ BaseTypes

alib::ListMA<Index::Node>* dxl::XLink::BaseTypes = nullptr

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.

Definition at line 186 of file xlink.hpp.

◆ CSSClasses

Styles dxl::XLink::CSSClasses

This is a list of HTML styles to apply to the link. The list is created in the method AssembleDisplay.

Definition at line 163 of file xlink.hpp.

◆ DidYouMeanFunctionOverload

alib::StdVectorMA<Index::Node> dxl::XLink::DidYouMeanFunctionOverload

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.

Definition at line 198 of file xlink.hpp.

◆ DidYouMeanNotATemplate

alib::StdVectorMA<Index::Node> dxl::XLink::DidYouMeanNotATemplate

A list of entries that are not templates, while a template type was searched.

Definition at line 208 of file xlink.hpp.

◆ DidYouMeanSameName

alib::StdVectorMA<Index::Node> dxl::XLink::DidYouMeanSameName

A list of target nodes with the same name.

Definition at line 193 of file xlink.hpp.

◆ DidYouMeanSpecializations

alib::StdVectorMA<Index::Node> dxl::XLink::DidYouMeanSpecializations

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.

Definition at line 212 of file xlink.hpp.

◆ DidYouMeanTemplateType

Index::Node dxl::XLink::DidYouMeanTemplateType

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.

Definition at line 202 of file xlink.hpp.

◆ DidYouMeanVariable

alib::StdVectorMA<Index::Node> dxl::XLink::DidYouMeanVariable

A list of entries that are variables, while the XLink's subscript does not match.

Definition at line 205 of file xlink.hpp.

◆ Display

alib::String dxl::XLink::Display = nullptr

The name of the entity to find (namespace, record, variable, function, enumeration element, type definition, etc).
If "*" 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 typename<...> 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 <...> is appended. <- This is a TODO(251221 08:27):

Definition at line 154 of file xlink.hpp.

◆ DisplayOriginalPos

alib::integer dxl::XLink::DisplayOriginalPos = 0

The position of the display string in the original search string. Note: This information is solely needed for implementing the ALib expression function LinkDisplay

Definition at line 159 of file xlink.hpp.

◆ Error

Errors dxl::XLink::Error = Errors::OK

Possible errors that occured during parsing the search string given by the user.

Definition at line 223 of file xlink.hpp.

◆ HTMLFileOfLocalLink

alib::files::FTree::ConstCursorHandle dxl::XLink::HTMLFileOfLocalLink = 0

The tree node of the HTML file which created this copy of the originally given local XLink.

Definition at line 177 of file xlink.hpp.

◆ HTMLLocations

alib::StdVectorMA<Location> dxl::XLink::HTMLLocations

The list of locations in HTML files. This list is unsorted as it is collected by the thread pool workers.

Definition at line 220 of file xlink.hpp.

◆ IsLocal

bool dxl::XLink::IsLocal = false

This flag is set when the specified link identifier starts with a dot character '.'. In this case, the XLink processing is changed in various ways.

Definition at line 231 of file xlink.hpp.

◆ IsUnderlyingTypeDef

bool dxl::XLink::IsUnderlyingTypeDef = false

This flag is set if "^" 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).
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.

Definition at line 245 of file xlink.hpp.

◆ KindSpec

Target::Kinds dxl::XLink::KindSpec = Target::UNSPECIFIED

Function arguments provided with the source XLink.

Definition at line 226 of file xlink.hpp.

◆ LinkString

alib::String dxl::XLink::LinkString

The original source string.

Definition at line 122 of file xlink.hpp.

◆ linkToParentScope

XLink* dxl::XLink::linkToParentScope = 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.

Definition at line 143 of file xlink.hpp.

◆ LocalLinkEntity

Index::ConstCursorHandle dxl::XLink::LocalLinkEntity = 0

The entity in the string tree that corresponds to the HTML file given with the field HTMLFileOfLocalLink.

Definition at line 181 of file xlink.hpp.

◆ Lock

alib::Lock dxl::XLink::Lock

The lock protecting the creation phase and as well allocator access.

Definition at line 102 of file xlink.hpp.

◆ MA

alib::MonoAllocator dxl::XLink::MA

The mono allocator used to create the members of the class.

Definition at line 99 of file xlink.hpp.

◆ MAX_SCOPE_DEPTH

int dxl::XLink::MAX_SCOPE_DEPTH = 20

staticconstexpr

The maximum number of scope hints and parents.

Definition at line 54 of file xlink.hpp.

◆ NextLocal

XLink* dxl::XLink::NextLocal = nullptr

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!

Definition at line 174 of file xlink.hpp.

◆ NoIndirectionWarning

bool dxl::XLink::NoIndirectionWarning = false

This flag is set if "^" is given at the start of the XLink which suppresses warnings if linking indirectly through base types or type definitions (or both).

Definition at line 238 of file xlink.hpp.

◆ NotFoundInHTML

bool dxl::XLink::NotFoundInHTML = false

This flag is set when the specified link identifier was not found in the HTML files.

Definition at line 234 of file xlink.hpp.

◆ Qualifiers

alib::String dxl::XLink::Qualifiers = nullptr

Function qualifiers like const, or nothrow provided with the source XLink.

Definition at line 136 of file xlink.hpp.

◆ scope

alib::String* dxl::XLink::scope

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.
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.

Definition at line 111 of file xlink.hpp.

◆ scopeHintsSize

int dxl::XLink::scopeHintsSize

protected

The number of strings in the array scope that are only hints.

Definition at line 114 of file xlink.hpp.

◆ scopeSize

int dxl::XLink::scopeSize = 0

protected

The number of strings in the array scope. Up to index scopeHintsSize - 1 the strings are only hints. The remaining represent full parent paths.

Definition at line 118 of file xlink.hpp.

◆ SourceLocations

alib::StdVectorMA<Location> dxl::XLink::SourceLocations

The list of locations in source files. This list is unsorted as it is collected by the thread pool workers.

Definition at line 216 of file xlink.hpp.

◆ SpecializationArgs

Target::TemplateArguments* dxl::XLink::SpecializationArgs = nullptr

Template arguments provided at the end of the source XLink, before the optional display, hence after the entity name.

Definition at line 133 of file xlink.hpp.

◆ Subscript

alib::String dxl::XLink::Subscript = nullptr

A variable subscript provided by the source XLink.

Definition at line 139 of file xlink.hpp.

◆ Targets

alib::StdVectorMA<Index::SearchResult> dxl::XLink::Targets

The list of results. Only when this list contains exactly one element, the XLink was successfully resolved.

Definition at line 167 of file xlink.hpp.

◆ TemplateArgs

Target::TemplateArguments* dxl::XLink::TemplateArgs = nullptr

Template arguments provided at the beginning of the source XLink, before path hints and the path, optionally introduced by the keyword template.

Definition at line 129 of file xlink.hpp.

◆ TypeDefinitionTargets

alib::ListMA<Index::Node>* dxl::XLink::TypeDefinitionTargets = nullptr

List of nodes pointing to type definition targets. This is used to find members which were addressed through type definitions.

Definition at line 190 of file xlink.hpp.

◆ WasPrinted

bool dxl::XLink::WasPrinted = 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.

Definition at line 249 of file xlink.hpp.

Constructor(s) / Destructor Details:

◆ XLink()

dxl::XLink::XLink ( )

inline

Constructor. Parses the given searchString and allocates the fields in the ma.

Definition at line 266 of file xlink.hpp.

Method Details:

◆ AssembleDisplay()

void dxl::XLink::AssembleDisplay ( )

Assembles the display string Display, if not already set. Called when an XLink was successfully resolved (size in Targets is 1).

Definition at line 513 of file xlink.cpp.

◆ CountLocalCopies()

int dxl::XLink::CountLocalCopies ( )

inline

Returns the number of local copies, hence the number of different HTML-files that this local link appeared in.

Returns: The number of local copies.

Definition at line 381 of file xlink.hpp.

◆ DbgReset()

void dxl::XLink::DbgReset ( )

inline

This method is need for the unit-tests and available only with debug-compilations.

Definition at line 278 of file xlink.hpp.

◆ findInherited()

void dxl::XLink::findInherited ( const decltype(TGTRecord::BaseTypes)& bases )

Recursive helper used by Search to find inherited parents.

Parameters

bases The list of base types.

Definition at line 462 of file xlink.cpp.

◆ GetLinkToParent()

XLink * dxl::XLink::GetLinkToParent ( )

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.
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 Search only in the case that this XLink contains a parent specification.

Returns: The requested XLink.

Definition at line 311 of file xlink.cpp.

◆ GetLocalCopy()

std::pair< XLink *, bool > dxl::XLink::GetLocalCopy ( const alib::files::File & htmlFile )

Returns this or a new XLink instance, with the given file attached. New copies are attached to the pointer NextLocal, which implements a forward list.

Parameters

htmlFile The file that the local link was found in.

Returns: An XLink with the given htmlFile set.

Definition at line 771 of file xlink.cpp.

◆ HasErrors()

bool dxl::XLink::HasErrors ( ) const

inline

Returns: true, if this links has errors (other than not resolved or ambiguous).

Definition at line 325 of file xlink.hpp.

◆ HasWarnings()

bool dxl::XLink::HasWarnings ( bool ignoreIndirects )

inline

Parameters

ignoreIndirects If true is given, indirect links which are not marked as such, are not listed in the error/warning output.

Returns: true, if this link has warnings.

Definition at line 330 of file xlink.hpp.

◆ Hint()

const alib::String & dxl::XLink::Hint ( int n ) const

inline

Returns: A scope-hint specified in this XLink.

Parameters

n	The number of the hint to get.

Definition at line 312 of file xlink.hpp.

◆ HintsSize()

int dxl::XLink::HintsSize ( ) const

inline

Returns: The number of strings in the array scope that are only hints.

Definition at line 298 of file xlink.hpp.

◆ IsGood()

bool dxl::XLink::IsGood ( bool ignoreIndirects )

inline

Parameters

ignoreIndirects Passed to internally used method HasWarnings.

Returns: true, if exactly one match was found, false otherwise.

Definition at line 341 of file xlink.hpp.

◆ IsParsed()

bool dxl::XLink::IsParsed ( ) const

inline

Returns: true, if this link was not only registered, but also parsed.

Definition at line 319 of file xlink.hpp.

◆ IsResolved()

bool dxl::XLink::IsResolved ( ) const

inline

Returns: true, if exactly one match was found, false otherwise.

Definition at line 322 of file xlink.hpp.

◆ Name()

alib::String & dxl::XLink::Name ( ) const

inline

Returns: The last component of the given path.

Definition at line 316 of file xlink.hpp.

◆ Parse()

void dxl::XLink::Parse ( )

Parses the given searchString and allocates the fields in the MA.

Definition at line 21 of file xlink.cpp.

◆ PrintError()

void dxl::XLink::PrintError	(	alib::Paragraphs &	out,
		const alib::String &	linkString,
		bool	suppressHints = false )

Writes a human-readable message on unresolved or ambiguous links.

Parameters

out	The target output paragraph formatter.
linkString	The original XLink string found in the output (and sources).
suppressHints	If given as `true`, no hints are printed.

Definition at line 802 of file xlink.cpp.

◆ ResolveTypeDef()

Index::Node dxl::XLink::ResolveTypeDef	(	const Index::Node &	startCursor,
		const alib::String &	origSearchString )

static

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.
Parameters

startCursor A reference to the cursor that points to the type definition.

origSearchString The original search string. This is used for log-output only.

Returns
The target cursor. On failure, this will be a root cursor.

Definition at line 402 of file xlink.cpp.

◆ Result() [1/2]

Index::SearchResult & dxl::XLink::Result ( )

inline

Returns: The result if IsResolved returns true. Otherwise, this is undefined behavior. In debug-builds, an ALib assertion is raised, if IsResolved is false.

Definition at line 347 of file xlink.hpp.

◆ Result() [2/2]

const Index::SearchResult & dxl::XLink::Result ( ) const

inline

Returns: The result if IsResolved returns true. Otherwise, this is undefined behavior. In debug-builds, an ALib assertion is raised, if IsResolved is false.

Definition at line 355 of file xlink.hpp.

◆ Scope()

const alib::String & dxl::XLink::Scope ( int n ) const

inline

Returns: A scope-parent specified in this XLink.

Parameters

n	The number of the parent to get.

Definition at line 307 of file xlink.hpp.

◆ ScopeSize()

int dxl::XLink::ScopeSize ( ) const

inline

The number of strings in the array scope. Up to index scopeHintsSize - 1 the strings are only hints. The remaining represent full parent paths.

Returns: The number of strings in the array scope.

Definition at line 303 of file xlink.hpp.

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

startCursor	A reference to the cursor that points to the type definition.
origSearchString	The original search string. This is used for log-output only.

Description:

Public Type Index:

Public Static Field Index:

Public Static Method Index:

Public Field Index:

Public Method Index:

Protected Field Index:

Enumeration Details:

◆ Errors

Field Details:

◆ Args

◆ BaseTypes

◆ CSSClasses

◆ DidYouMeanFunctionOverload

◆ DidYouMeanNotATemplate

◆ DidYouMeanSameName

◆ DidYouMeanSpecializations

◆ DidYouMeanTemplateType

◆ DidYouMeanVariable

◆ Display

◆ DisplayOriginalPos

◆ Error

◆ HTMLFileOfLocalLink

◆ HTMLLocations

◆ IsLocal

◆ IsUnderlyingTypeDef

◆ KindSpec

◆ LinkString

◆ linkToParentScope

◆ LocalLinkEntity

◆ Lock

◆ MA

◆ MAX_SCOPE_DEPTH

◆ NextLocal

◆ NoIndirectionWarning

◆ NotFoundInHTML

◆ Qualifiers

◆ scope

◆ scopeHintsSize

◆ scopeSize

◆ SourceLocations

◆ SpecializationArgs

◆ Subscript

◆ Targets

◆ TemplateArgs

◆ TypeDefinitionTargets

◆ WasPrinted

Constructor(s) / Destructor Details:

◆ XLink()

Method Details:

◆ AssembleDisplay()

◆ CountLocalCopies()

◆ DbgReset()

◆ findInherited()

◆ GetLinkToParent()

◆ GetLocalCopy()

◆ HasErrors()

◆ HasWarnings()

◆ Hint()

◆ HintsSize()

◆ IsGood()

◆ IsParsed()

◆ IsResolved()

◆ Name()

◆ Parse()

◆ PrintError()

◆ ResolveTypeDef()

◆ Result() [1/2]

◆ Result() [2/2]

◆ Scope()

◆ ScopeSize()