eĿlipsis: include/ellipsis-builtins.dirs File Reference

Searching...

No Matches

Builtin macro definitions provided by eĿlipsis. More...

Macros
Object-like builtins that are not functional
#define	__COUNTER__
	A global counter that advances at each evaluation.

#define	__DATE__
	The compilation date as required by the C standard.

#define	__ELLIPSIS__ 20241125
	EĿlipsis's version number.

#define	__FILE__
	The current source file as required by the C standard.

#define	__FILENO__
	The current source file encoded in a unique number.

#define	__INCLUDE_DEPTH__
	The current depth of nested includes.

#define	__INTEGER_DATE__
	The compilation date similar to __DATE__ but as an integer suitable for version numbers.

#define	__ISO_DATE__
	The compilation date similar to __DATE__ but in the ISO date format.

#define	__limit_embed __limit_embed
	A feature test functionality obtain the number of bytes in a data resource.

#define	__limit_include __limit_include
	A feature test functionality obtain the number of lines in a source files.

#define	__LINE__
	The current physical source line as required by the C standard.

#define	__LINENO__
	The first physical source line of the current logical line.

#define	__TIME__
	The compilation time as required by the C standard.

#define	defined defined
	A place holder for the `defined` preprocessor test as required by the C standard.

#define	false false
	The constant `false` made accessible to the preprocessor.

#define	true true
	The constant `true` made accessible to the preprocessor.

Expanding builtins that expand their arguments
#define	__has_embed(...)
	A feature test functionality to search for data resources.

#define	__has_extension(...)
	A test for compiler extensions specific for `clang`

#define	__has_feature(...)
	A feature test specific for `clang`

#define	__has_include(...)

#define	__is_identifier(...)
	A test specific for `clang` to see if a name is an identifier or a keyword.

Non-expanding builtins that do not expand their arguments
#define	__ANY__(...)
	Test if any of the tokens would remain after a first macro replacement, where undefined identifiers account as-if defined as empty.

#define	__BIND__(...)
	Generate an anonymous macro with a definition as if given by the argument list.

#define	__CLEAR__(...)
	Clear the value of a macro holding an integer.

#define	__COMMAS__(...)
	Count the number of top level commas in `__VA_ARGS`

#define	__DECREMENT__(...)
	Decrement the value of a macro holding an integer.

#define	__EMPTY__(...)
	Test if `__VA_ARGS__` is empty or not.

#define	__ERROR__(...)
	Use the `__VA_ARGS` as an error message and abord compilation.

#define	__EVALUATE__(...)
	Evaluate the arguments as if in an #if preprocessor conditional.

#define	__EVALUATE_BIN__(...)
	Evaluate the arguments as if in an #if preprocessor conditional and produce a binary literal.

#define	__EVALUATE_DEC__(...)
	Evaluate the arguments as if in an #if preprocessor conditional and produce a decimal literal.

#define	__EVALUATE_HEX__(...)
	Evaluate the arguments as if in an #if preprocessor conditional and produce a hexdecimal literal.

#define	__EVALUATE_OCT__(...)
	Evaluate the arguments as if in an #if preprocessor conditional and produce a octal literal.

#define	__FREEZE__(...)
	Protect the identifier in the argument from being expanded.

#define	__INCREMENT__(...)
	Increment the value of a macro holding an integer.

#define	__MANGLE__(...)
	Mangle identifiers.

#define	__TOLOWER__(...)
	Convert the contents of the single token argument to all lowercase.

#define	__TOUPPER__(...)
	Convert the contents of the single token argument to all uppercase.

#define	__WARNING__(...)
	Use the `__VA_ARGS__` as warning message and continue compilation.

Detailed Description

Builtin macro definitions provided by eĿlipsis.

These are macros that are builtin macros that either correspond to standard C features or to extensions. Most of them would not be implementable directly but need some compiler magic. In particular, some of those that receive parameters do not expand their token list before processing.

Warning: The macros in this group may not be undefined or redefined

Note: DISCLAIMER.

Macro Definition Documentation

◆ ANY

#define __ANY__ ( ... )

Test if any of the tokens would remain after a first macro replacement, where undefined identifiers account as-if defined as empty.

Typically this would be used as in

%:if __ANY__(TOTO)
...
%:endif

where TOTO is some macro. This would be true if the expansion list of TOTO has any contents, regardless of whether or not multiple expansion would again reduce that to empty. If TOTO is not defined as a macro, this is false.

This can also be used with a list of names as in __ANY__(TOTO TUTU TATA) where this would test all three names and return true if any of them has contents as a macro. Note that a use as in __ANY__(TOTO, TUTU, TATA) would always return true, because of the commas.

Warning: This macro may not be undefined or changed otherwise

◆ BIND

#define __BIND__ ( ... )

Generate an anonymous macro with a definition as if given by the argument list.

This does almost the same thing as a #bind directive. The differences are

The macro that is defined has a random name and that random name is inserted in place.
If you use __BIND__ inside another macro definition, say TOTO, it is not expanded at the time of that definition but only later when TOTO is invoked. So any arguments that are passed into the invocation of TOTO are then replaced in the definition of the anonymous macro.
__BIND_ARGS__, __BIND_OPT__ and __BIND_TAIL__ can be used instead of the corresponding __VA_ features. This avoids that these would be interpreted by the surrounding macro definition.

It can be used when you locally want to apply a macro that saves some local state to a list of arguments. For example with

# define ELLIPSIS_ISANY(X, ...) __BIND__((Y, ...) ((X) ≡ (Y)) __BIND_OPT__(||)__BIND_TAIL__())(__VA_ARGS__)

the invocation

ELLIPSIS_ISANY(precious, a, b, c)

ELLIPSIS_ISANY

#define ELLIPSIS_ISANY(X, …)

Test equality for an expression against a set of expressions.

Definition ellipsis-cumulative.dirs:23

would be as if a macro was bound

#bind HURLY(Y, ...) ((precious) ≡ (Y)) __VA_OPT__(||)__VA_TAIL__()

Note that here the first argument to ELLIPSIS_ISANY, precious, is fixed into the generated anonymous macro. Then that macro is in turned tail called as

HURLY(a, b, c)

with the end result of something like

((precious) ≡ (a)) || ((precious) ≡ (b)) || ((precious) ≡ (c))

See also: #bind; Tail recursion

Warning: If this construct is not followed by ( as for all macros the crude internal name of this macro remains in the input stream. Although this could probably be used to some extent, this is not recommended.; The validity of the constructed macro is limited in the same way as macros that are defined with #bind.; This macro may not be undefined or changed otherwise

◆ CLEAR

#define __CLEAR__ ( ... )

Clear the value of a macro holding an integer.

This builtin should receive exactly one parameter, the name of the macro for which the value is to be cleared. The result is a token with value 0 or 0U.

Remarks: If the macro is not yet defined, the macro is initialized with a signed zero, 0.

Warning: This macro may not be undefined or changed otherwise

◆ COMMAS

#define __COMMAS__ ( ... )

Count the number of top level commas in __VA_ARGS

Top level here refers to commas that are not enclosed in any parenthesis. E.g __COMMAS__(,) returns 1, whereas in __COMMAS__((,)) the comma is protected and the return is 0.

Warning: Parenthesis in __VA_ARGS__ should be properly nested.; This macro may not be undefined or changed otherwise

◆ COUNTER

#define __COUNTER__

A global counter that advances at each evaluation.

This uses a hidden state that can only be observed by modifying it.

See also: INCREMENT

Warning: This macro may not be undefined or changed otherwise

◆ DATE

#define __DATE__

The compilation date as required by the C standard.

Warning: This macro may not be undefined or changed otherwise

◆ DECREMENT

#define __DECREMENT__ ( ... )

Decrement the value of a macro holding an integer.

This builtin should receive exactly one parameter, the name of the macro for which the value is to be decremented. The result is a token with that decremented value.

Remarks: If the macro is not yet defined, the macro is first initialized with a signed zero and the result is a 1 token.

Warning: This macro may not be undefined or changed otherwise

◆ ELLIPSIS

#define __ELLIPSIS__ 20241125

EĿlipsis's version number.

Warning: This macro may not be undefined or changed otherwise

◆ EMPTY

#define __EMPTY__ ( ... )

Test if __VA_ARGS__ is empty or not.

Warning: This macro may not be undefined or changed otherwise

◆ ERROR

#define __ERROR__ ( ... )

Use the __VA_ARGS as an error message and abord compilation.

Warning: This macro may not be undefined or changed otherwise

◆ EVALUATE

#define __EVALUATE__ ( ... )

Evaluate the arguments as if in an #if preprocessor conditional.

In most cases this probably is not what you want because this primitive does not expand the argument (so all identifier lead to value 0). Also the result is not necessarily a literal but just an internal representation of the integer.

Warning: This macro may not be undefined or changed otherwise

◆ __EVALUATE_BIN__

#define __EVALUATE_BIN__ ( ... )

Evaluate the arguments as if in an #if preprocessor conditional and produce a binary literal.

In most cases this probably is not what you want because this primitive does not expand the argument (so all identifier lead to value 0). Most likely you would want to use __EXPAND_BIN__ or __EXPAND_BIN_U__ instead.

Warning: This macro may not be undefined or changed otherwise

◆ __EVALUATE_DEC__

#define __EVALUATE_DEC__ ( ... )

Evaluate the arguments as if in an #if preprocessor conditional and produce a decimal literal.

Warning: This macro may not be undefined or changed otherwise

◆ __EVALUATE_HEX__

#define __EVALUATE_HEX__ ( ... )

Evaluate the arguments as if in an #if preprocessor conditional and produce a hexdecimal literal.

Warning: This macro may not be undefined or changed otherwise

◆ __EVALUATE_OCT__

#define __EVALUATE_OCT__ ( ... )

Evaluate the arguments as if in an #if preprocessor conditional and produce a octal literal.

Warning: This macro may not be undefined or changed otherwise

◆ FILE

#define __FILE__

The current source file as required by the C standard.

Warning: This macro may not be undefined or changed otherwise

◆ FILENO

#define __FILENO__

The current source file encoded in a unique number.

Warning: This macro may not be undefined or changed otherwise

◆ FREEZE

#define __FREEZE__ ( ... )

Protect the identifier in the argument from being expanded.

Warning: This macro may not be undefined or changed otherwise

◆ __has_embed

#define __has_embed ( ... )

A feature test functionality to search for data resources.

Since C23.

You may use this to check if a particular file is in one of the paths used for embed or embed_resource. For backwards compatibility with older version of C you may also use this in conditional preprocessing in the form of defined(__has_embed) to see if this feature is implemented at all.

Warning: This macro may not be undefined or changed otherwise

◆ __has_extension

#define __has_extension ( ... )

A test for compiler extensions specific for clang

Warning: This macro may not be undefined or changed otherwise

◆ __has_feature

#define __has_feature ( ... )

A feature test specific for clang

Warning: This macro may not be undefined or changed otherwise

◆ __has_include

#define __has_include ( ... )

◆ __INCLUDE_DEPTH__

#define __INCLUDE_DEPTH__

The current depth of nested includes.

◆ INCREMENT

#define __INCREMENT__ ( ... )

Increment the value of a macro holding an integer.

This builtin should receive exactly one parameter, the name of the macro for which the value is to be incremented. The result is a token with that incremented value.

Remarks: If the macro is not yet defined, the macro is first initialized with a signed zero and the result is a 1 token.

Warning: This macro may not be undefined or changed otherwise

◆ __INTEGER_DATE__

#define __INTEGER_DATE__

The compilation date similar to __DATE__ but as an integer suitable for version numbers.

Warning: This macro may not be undefined or changed otherwise

◆ __is_identifier

#define __is_identifier ( ... )

A test specific for clang to see if a name is an identifier or a keyword.

Warning: This macro may not be undefined or changed otherwise

◆ __ISO_DATE__

#define __ISO_DATE__

The compilation date similar to __DATE__ but in the ISO date format.

Warning: This macro may not be undefined or changed otherwise

◆ __limit_embed

#define __limit_embed __limit_embed

A feature test functionality obtain the number of bytes in a data resource.

You may use this to obtain the number of bytes in a data resource used for embed or embed_resource. For backwards compatibility with older version of C you may also use this in conditional preprocessing in the form of defined(__limit_embed) to see if this feature is implemented at all.

Warning: This macro may not be undefined or changed otherwise

◆ __limit_include

#define __limit_include __limit_include

A feature test functionality obtain the number of lines in a source files.

You may use this to obtain the number of lines in a source file used for include, include_source or include_directives. For backwards compatibility with older version of C you may also use this in conditional preprocessing in the form of defined(__limit_include) to see if this feature is implemented at all.

Warning: This macro may not be undefined or changed otherwise

◆ LINE

#define __LINE__

The current physical source line as required by the C standard.

Warning: This macro may not be undefined or changed otherwise

◆ LINENO

#define __LINENO__

The first physical source line of the current logical line.

Warning: This macro may not be undefined or changed otherwise

◆ MANGLE

#define __MANGLE__ ( ... )

Mangle identifiers.

This uses an internal algorithm to produce indentifiers that are composed only of alphanumeric characters. E.g eĿlipsis converts __MANGLE__(toto::hui) into _ZN4toto3huiE. This functionality needed internally to produce macro names corresponding to C attributes, but could also be used by other features that need an abstraction to compose names hierarchically.

Warning: This macro may not be undefined or changed otherwise

◆ TIME

#define __TIME__

The compilation time as required by the C standard.

Warning: This macro may not be undefined or changed otherwise

◆ TOLOWER

#define __TOLOWER__ ( ... )

Convert the contents of the single token argument to all lowercase.

The argument may be any kind of token, in particular an identifier, a number, a string or character literal. It simply transforms all letters that have a case correspondence, even within a string or character literal. In particular it also transforms number representations that contain letters to their lowercase, e.g. 0XB.34AFP+1 to 0xb.34afp+1.

This only concerns the default Unicode case mapping facilities, in particular those that are in ASCII. Language specific mappings are not used.

See also: special lowercase letters that map to conventional uppercase letters; bijections between lowercase and uppercase letters

Warning: This macro may not be undefined or changed otherwise

◆ TOUPPER

#define __TOUPPER__ ( ... )

Convert the contents of the single token argument to all uppercase.

This only concerns the default Unicode case mapping facilities, in particular those that are in ASCII. Language specific mappings such as the German ß → SS are not used.

See also: special uppercase letters that map to conventional lowercase letters; bijections between lowercase and uppercase letters

Warning: This macro may not be undefined or changed otherwise

◆ WARNING

#define __WARNING__ ( ... )

Use the __VA_ARGS__ as warning message and continue compilation.

Warning: This macro may not be undefined or changed otherwise

◆ defined

#define defined defined

A place holder for the defined preprocessor test as required by the C standard.

Warning: This macro may not be undefined or changed otherwise

◆ false

#define false false

The constant false made accessible to the preprocessor.

Warning: This macro may not be undefined or changed otherwise

◆ true

#define true true

The constant true made accessible to the preprocessor.

Warning: This macro may not be undefined or changed otherwise

Macros

Detailed Description

Macro Definition Documentation

◆ __ANY__

◆ __BIND__

◆ __CLEAR__

◆ __COMMAS__

◆ __COUNTER__

◆ __DATE__

◆ __DECREMENT__

◆ __ELLIPSIS__

◆ __EMPTY__

◆ __ERROR__

◆ __EVALUATE__