Description:

This is a central class of library module ALib Expressions used to compile expression strings.

For information about general use and features of this class consult the ALib Expressions User Manual.

Friends

class Expression

Definition at line 89 of file compiler.hpp.

#include <compiler.hpp>

Inheritance diagram for Compiler:

[legend]

Collaboration diagram for Compiler:

[legend]

Public Type Index:
enum class	BuiltInPlugins { NONE = 0 , ALL = -1 , ElvisOperator = (1 << 1) , AutoCast = (1 << 2) , Arithmetics = (1 << 3) , Math = (1 << 4) , Strings = (1 << 5) , ALIB_IF_CAMP }

using	Plugins = std::vector<lang::PluginContainer<CompilerPlugin, CompilePriorities>::Slot>

Public Type Index: inherited from PluginContainer< CompilerPlugin, CompilePriorities >
using	TPlugin

using	TPriorities

Public Field Index:
HashMap< String, String, alib::hash_string_ignore_case< character >, alib::equal_to_string_ignore_case< character > >	AlphabeticBinaryOperatorAliases

HashMap< String, String, alib::hash_string_ignore_case< character >, alib::equal_to_string_ignore_case< character > >	AlphabeticUnaryOperatorAliases

HashMap< String, int >	BinaryOperators

BuiltInPlugins	CfgBuiltInPlugins = BuiltInPlugins::ALL

Compilation	CfgCompilation = Compilation::DEFAULT

SPFormatter	CfgFormatter

strings::util::Token	CfgNestedExpressionFunction

String	CfgNestedExpressionOperator = A_CHAR("*")

String	CfgNestedExpressionThrowIdentifier

Normalization	CfgNormalization = Normalization::DEFAULT

std::vector< AString >	CfgNormalizationDisallowed

ExpressionRepository *	Repository = nullptr

List< String >	UnaryOperators

Public Method Index:
ALIB_API	Compiler ()

virtual ALIB_API	~Compiler ()

void	AddBinaryOperator (const String &symbol, int precedence)

virtual ALIB_API bool	AddNamed (const String &name, const String &expressionString)

ALIB_API void	AddType (Type sample, const NString &name)

void	AddUnaryOperator (const String &symbol)

virtual ALIB_API SPExpression	Compile (const String &expressionString)

int	GetBinaryOperatorPrecedence (const String &symbol)

virtual ALIB_API SPExpression	GetNamed (const String &name)

bool	RemoveNamed (const String &name)

ALIB_API void	SetupDefaults ()

ALIB_API NString	TypeName (Type box)

ALIB_API void	WriteFunctionSignature (ArgIterator begin, ArgIterator end, AString &target)

ALIB_API void	WriteFunctionSignature (Box **boxArray, size_t qty, AString &target)

Public Method Index: inherited from PluginContainer< CompilerPlugin, CompilePriorities >
	~PluginContainer ()

integer	CountPlugins ()

TPlugin *	GetPlugin (integer number)

TPlugin *	GetPlugin (TPriorities priority)

TPluginType *	GetPluginTypeSafe ()

TPluginType *	GetPluginTypeSafe (TPriorities priority)

bool	HasPlugins ()

void	InsertPlugin (TPlugin *plugin, TPriorities priority, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)

void	RemovePlugin (integer idx)

bool	RemovePlugin (TPlugin *plugIn)

TPlugin *	RemovePlugin (TPriorities priority)

Type Definition Details:

◆ Plugins

using Plugins = std::vector<lang::PluginContainer<CompilerPlugin, CompilePriorities>::Slot>

Alias shortcut to the type of the plug-in vector inherited from PluginContainer.

Definition at line 99 of file compiler.hpp.

Enumeration Details:

◆ BuiltInPlugins

enum class BuiltInPlugins

strong

Bitwise enum class that lists the plug-ins built-into ALib expression library. This bitfield is used with method SetupDefaults, which reads the flags set in CfgBuiltInPlugins and installs the plug-ins accordingly.

Enumerator
NONE	Installs no plug-in.
ALL	Installs all plug-ins.
ElvisOperator	Installs plugins::ElvisOperator .
AutoCast	Installs plugins::AutoCast .
Arithmetics	Installs plugins::Arithmetics .
Math	Installs plugins::Math .
Strings	Installs plugins::Strings .
ALIB_IF_CAMP	Installs plugins::DateAndTime . )

Definition at line 247 of file compiler.hpp.

Field Details:

◆ allocator

MonoAllocator allocator

protected

Memory for used for permanent allocations during the set-up phase. Later it is also used for temporary allocations during compilation and reset to its state after setup.

Definition at line 108 of file compiler.hpp.

◆ AlphabeticBinaryOperatorAliases

HashMap<String, String, alib::hash_string_ignore_case<character>, alib::equal_to_string_ignore_case<character> > AlphabeticBinaryOperatorAliases

This public map allows to define alias names for binary operators. Such names must consist only of alphabetic characters.

Flag Compilation::DefaultAlphabeticOperatorAliases controls if method SetupDefaults adds the aliases defined with resourced data records of enumeration DefaultAlphabeticBinaryOperatorAliases to this map.

Definition at line 166 of file compiler.hpp.

◆ AlphabeticUnaryOperatorAliases

HashMap<String, String, alib::hash_string_ignore_case<character>, alib::equal_to_string_ignore_case<character> > AlphabeticUnaryOperatorAliases

This public map allows to define alias names for unary operators. Such names must consist only of alphabetic characters.

Flag Compilation::DefaultAlphabeticOperatorAliases controls if method SetupDefaults adds the aliases defined with resourced data records of enumeration DefaultAlphabeticUnaryOperatorAliases to this map.

Definition at line 154 of file compiler.hpp.

◆ BinaryOperators

HashMap<String, int> BinaryOperators

The list of binary operators. The map stores the precedences.

To define a new binary operator, entry may be added prior to invoking SetupDefaults using method AddBinaryOperator.

Flag Compilation::DefaultUnaryOperators controls if method SetupDefaults adds operators resourced with enumeration DefaultBinaryOperators .

Definition at line 197 of file compiler.hpp.

◆ CfgBuiltInPlugins

BuiltInPlugins CfgBuiltInPlugins = BuiltInPlugins::ALL

Bitfield that defines the built-in compiler plug-ins that are created and inserted by method SetupDefaults.

Defaults to BuiltInPlugins::ALL

Note: The built-in plug-ins are allowed to be shared by different compiler instances. To reach that, they must not be disabled here (or method SetupDefaults must be omitted) and instead created once and registered with the compiler using inherited method lang::PluginContainer::InsertPlugin . In that case, parameter responsibility of that method has to be provided as Responsibility::KeepWithSender.

Definition at line 275 of file compiler.hpp.

◆ CfgCompilation

Compilation CfgCompilation = Compilation::DEFAULT

Compilation flags.

Definition at line 317 of file compiler.hpp.

◆ CfgFormatter

SPFormatter CfgFormatter

Formatter used throughout all phases of the life-cycle of an expression:

Used for parsing expression strings (Using the encapsulated NumberFormat object. This is also the reason, why the type of formatter is Formatter and not its more abstract base % Formatter.)
Used for the generation of the normalized expression strings.
Used for the generation of constant string objects during compilation.
Used for the generation of string objects during evaluation.

For the latter two, a copy of the pointer is provided through field Scope::Formatter . It is important not to change the formatting parameters in between the creation of the compile-time scope and the creation of the evaluation-time scope. If done, the expression results could differ when optimizations during compilation are performed.

In the constructor of this class, a clone of the ALib default formatter is set here.

Definition at line 366 of file compiler.hpp.

◆ CfgNestedExpressionFunction

strings::util::Token CfgNestedExpressionFunction

Name descriptor for nested expression function. Defaults to "Expression" with minimum abbreviation of 4 characters, ignoring letter case.
Resourced with key "EF"

See also: Manual chapter 10. Nested Expressions.

Definition at line 304 of file compiler.hpp.

◆ CfgNestedExpressionOperator

String CfgNestedExpressionOperator = A_CHAR("*")

The operator defined in this public field is used to address nested expressions. The operator used can be customized to any defined (!) unary operator.

To disable nested expression parsing, change to empty or nulled string.

Note: If changed, the change hast to be made prior to invoking SetupDefaults. Otherwise, the default configuration for verbal operator aliases would be set in effect to a wrong (or disabled) target operator.

Defaults to "*".

See also: Manual chapter 10. Nested Expressions.

Definition at line 294 of file compiler.hpp.

◆ CfgNestedExpressionThrowIdentifier

String CfgNestedExpressionThrowIdentifier

Keyword used with optional third parameter of expression function. Defaults to "throw". Resourced with key "EF"

See also: Manual chapter 10. Nested Expressions.

Definition at line 312 of file compiler.hpp.

◆ CfgNormalization

Normalization CfgNormalization = Normalization::DEFAULT

Flags that allow to tweak the result of the normalization of the originally parsed expression string.

Definition at line 323 of file compiler.hpp.

◆ CfgNormalizationDisallowed

std::vector<AString> CfgNormalizationDisallowed

This list is used with the normalization of the expression string. It contains strings, which are not allowed to appear in normalized expression strings.

In the current library version, such strings might occur only if flags Normalization::UnaryOpSpace , Normalization::UnaryOpSpaceIfUnaryFollows or Normalization::BinaryOpSpaces are not set. As a sample see expression:

     1 - -2

If no space is written after binary operators, this expression would be normalized to: 1–2

While this just looks irritating to a homo sapiens, it would be even illegal if well known C++ operator – was supported. Therefore, string "--" is added to this map in method SetupDefaults, which forces the normalization logic to insert a space, even if spaces are otherwise configured to be omitted.

Definition at line 346 of file compiler.hpp.

◆ namedExpressions

HashMap< AString, SPExpression, std::hash <String>, std::equal_to<String> > namedExpressions

protected

The map of 'named' expressions.

Definition at line 121 of file compiler.hpp.

◆ parser

detail::Parser* parser = nullptr

protected

The expression parser.

Definition at line 111 of file compiler.hpp.

◆ Repository

ExpressionRepository* Repository = nullptr

Optional pointer to a default or custom implementation of a repository that provides expression strings for named nested expressions.

See also: Manual chapter 10.5 Automated Named Expressions.

Definition at line 374 of file compiler.hpp.

◆ typeMap

HashMap<TypeFunctors::Key, NAString, TypeFunctors::Hash, TypeFunctors::EqualTo> typeMap

protected

The map of Type names and bit flag values.

Definition at line 116 of file compiler.hpp.

◆ UnaryOperators

List<String> UnaryOperators

The list of unary operators. To define a new unary operator, method AddUnaryOperator should be used. In debug-builds, the methods asserts that no double insertions are performed.

Custom insertions may be performed before or after invoking SetupDefaults, but before a first expression is compiled.

Flag Compilation::DefaultUnaryOperators controls if method SetupDefaults adds operators resourced with enumeration DefaultUnaryOperators .

Definition at line 142 of file compiler.hpp.

Constructor(s) / Destructor Details::

◆ Compiler()

Compiler ( )

Constructor. Construction usually is three steps:

Create class instance
Set the various configuration options (fields prefixed Cfg).
Invoke SetupDefaults.

Definition at line 97 of file compiler.cpp.

Here is the call graph for this function:

◆ ~Compiler()

~Compiler ( )

virtual

Destructor

Definition at line 143 of file compiler.cpp.

Method Details:

◆ AddBinaryOperator()

void AddBinaryOperator	(	const String &	symbol,
		int	precedence )

inline

Adds a binary operator to this expression compiler. This method should be invoked prior to prior to invoking SetupDefaults.

Operator symbols must be added only once.

Parameters

symbol	The operator symbol.
precedence	The precedence of the operator.

Definition at line 208 of file compiler.hpp.

◆ AddNamed()

bool AddNamed	(	const String &	name,
		const String &	expressionString )

virtual

Compiles the given expressionString and adds a compiled expression to the map of named expressions.

Parameters

name	The name used to map the expression.
expressionString	The string to parse. If nulled, entry name is removed (if existing).

Returns: true if an expression with the same named existed and was replaced. Otherwise returns false.

Definition at line 357 of file compiler.cpp.

Here is the call graph for this function:

◆ AddType()

void AddType	(	Type	sample,
		const NString &	name )

Registers a (custom) type name with this compiler. The name will be used to display a type name to end-users, for example, when malformed expressions throw an exception.

The built-in types get registered in the constructor of the compiler, where the type names are read from the ResourcePool of static library object EXPRESSIONS .

It is recommended that custom plug-ins invoke this method in their constructor.

Note: There is no general need to register types for using them with ALib Expressions . Parameter name of this method is exclusively used to generate textual, human readable output!

Parameters

sample	A sample value of the type, which is implicitly boxed when passed.
name	The name of the type.

Definition at line 424 of file compiler.cpp.

Here is the call graph for this function:

◆ AddUnaryOperator()

void AddUnaryOperator ( const String & symbol )

inline

Adds an unary operator to this expression compiler. This method should be invoked prior to prior to invoking SetupDefaults.

Operator symbols must be added only once.

Parameters

symbol The operator symbol.

Definition at line 176 of file compiler.hpp.

◆ Compile()

SPExpression Compile ( const String & expressionString )

virtual

Firstly, this method parses the given expression string thereby builds an intermediate internal abstract syntax tree . This tree is then translated into a detail::Program which evaluates the expression in respect to a Scope when executed.

For building the program, attached CompilerPlugin instances are queried.

During this process, a normalized version of the input string is always created. While the original input string can be accessed with Expression::GetOriginalString , the normalized version can be retrieved after the compilation with method Expression::GetNormalizedString . During compilation, the normalization rules (flags) stored in field CfgNormalization are applied.

For compilation, a compile-time scope object is created by calling virtual method getCompileTimeScope. If not overwritten, a standard scope object is used. If custom callbacks exists that are invokable at compile-time (to perform program optimization) and that at the same time rely on custom mechanics provided with a custom scope class, then a custom, derived version of this class has to be used that overrides method getCompileTimeScope accordingly.

Parameters

expressionString The string to parse.

Returns: A shared pointer to the compiled expression. Contains nullptr on failure.

Definition at line 251 of file compiler.cpp.

Here is the call graph for this function:

◆ GetBinaryOperatorPrecedence()

int GetBinaryOperatorPrecedence ( const String & symbol )

inline

Returns the precedence of given operator symbol.

Parameters

symbol The operator symbol.

Returns: The precedence of the operator as defined with AddBinaryOperator.

Definition at line 222 of file compiler.hpp.

◆ getCompileTimeScope()

Scope * getCompileTimeScope ( )

protectedvirtual

This virtual method is called by Compile to create the scope object used for allocations that are made for intermediate results at compile-time.

Compile-time allocations occur when expression terms that use purely constant arguments are evaluated at compile-time. Such optimization consequently leads to the invocation of callback functions at compile-time.

If now, custom callback functions rely on custom allocation mechanics, provided with custom scope types, then this method has to be overridden to return such custom scope object.

Returns: The default implementation returns the standard scope object. For its construction, field CfgFormatter is provided.
Derived compilers may need to return a scope object of a derived type.

Definition at line 151 of file compiler.cpp.

◆ GetNamed()

SPExpression GetNamed ( const String & name )

virtual

Returns a named expression previously defined using AddNamed. In the case that no expression with the given named was defined and optional interface Repository is set, then this interface is used to retrieve a corresponding expression string and compile the named expression 'on the fly'.

See also: Manual chapter 10.5 Automated Named Expressions.

Parameters

name	The name of the expression.

Returns: In case of success a shared pointer to the expression.

Definition at line 389 of file compiler.cpp.

Here is the call graph for this function:

◆ getOptimizedExpressionString()

void getOptimizedExpressionString ( Expression * expression )

protected

Implements Expression::GetOptimizedString .

Parameters

expression the expression to generate an optimized string for.

Definition at line 332 of file compiler.cpp.

Here is the call graph for this function:

◆ RemoveNamed()

bool RemoveNamed ( const String & name )

inline

Removes a named expression. This is just a shortcut to AddNamed, providing a nulled string for parameter expressionString .

Parameters

name	The name of the expression to be removed.

Returns: true if an expression with the given name existed and was removed. Otherwise returns false.

Definition at line 540 of file compiler.hpp.

Here is the call graph for this function:

◆ SetupDefaults()

void SetupDefaults ( )

Completes construction according to configuration options provided with fields prefixed Cfg. In detail, the following actions are performed:

If flag Compilation::DefaultUnaryOperators is set in field CfgCompilation, then
- the unary operators listed in the enum records of DefaultUnaryOperators are added using AddUnaryOperator.
- If flag Compilation::DefaultAlphabeticOperatorAliases is set in field CfgCompilation, then the alphabetic alias names found in the data records of enumeration DefaultAlphabeticUnaryOperatorAliases are set in field AlphabeticUnaryOperatorAliases. (As of the current version this is only the token NOT aliasing operator "!".
If flag Compilation::DefaultBinaryOperators is set in field CfgCompilation, then
- the binary operators listed in the data records of enumeration DefaultBinaryOperators are added using AddBinaryOperator.
- If flag Compilation::AllowSubscriptOperator is not set, the subscript operator is omitted.
- If flag Compilation::DefaultAlphabeticOperatorAliases is set in field CfgCompilation, then the alphabetic alias names found in the data records of enumeration DefaultAlphabeticBinaryOperatorAliases are set in field AlphabeticBinaryOperatorAliases. (As of the current version this is only the token NOT aliasing operator "!".
Strings "++" and "--" are added to field CfgNormalizationDisallowed to prevent the unintentional creation of these potential operators in normalizations. (This way, a space character will be added between binary "+" and unary "+", respectively binary "-" and unary "-" operators, even if the normalization options do not suggest to do this.
Depending on the flags set in CfgBuiltInPlugins, the plug-ins listed in enumeration BuiltInPlugins are created and added.

Definition at line 160 of file compiler.cpp.

Here is the call graph for this function:

◆ TypeName()

NString TypeName ( Type box )

Returns the name of the type of the boxed value. Note that custom types need to be registered with method AddType.

If given argument box is a void box, the returned string is "NONE".

Parameters

box	The box to receive the type name for.

Returns: The type name as string.

Definition at line 432 of file compiler.cpp.

Here is the call graph for this function:

◆ WriteFunctionSignature() [1/2]

ALIB_WARNINGS_RESTORE void WriteFunctionSignature	(	ArgIterator	begin,
		ArgIterator	end,
		AString &	target )

Writes the signature of an argument list to a string buffer.

Parameters

begin	Iterator to the first argument.
end	End-iterator.
target	The string to write into.

Definition at line 474 of file compiler.cpp.

Here is the call graph for this function:

◆ WriteFunctionSignature() [2/2]

ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE void WriteFunctionSignature	(	Box **	boxArray,
		size_t	qty,
		AString &	target )

Writes the signature of a function (as for example found in Calculus::FunctionEntry ) to a string buffer.

Parameters

boxArray	The start of the array of pointers.
qty	The array's length.
target	The string to write into.

Definition at line 448 of file compiler.cpp.

Here is the call graph for this function:

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

Description:

Friends

Public Type Index:

Public Field Index:

Public Method Index:

Type Definition Details:

◆ Plugins

Enumeration Details:

◆ BuiltInPlugins

Field Details:

◆ allocator

◆ AlphabeticBinaryOperatorAliases

◆ AlphabeticUnaryOperatorAliases

◆ BinaryOperators

◆ CfgBuiltInPlugins

◆ CfgCompilation

◆ CfgFormatter

◆ CfgNestedExpressionFunction

◆ CfgNestedExpressionOperator

◆ CfgNestedExpressionThrowIdentifier

◆ CfgNormalization

◆ CfgNormalizationDisallowed

◆ namedExpressions

◆ parser

◆ Repository

◆ typeMap

◆ UnaryOperators

Constructor(s) / Destructor Details::

◆ Compiler()

◆ ~Compiler()

Method Details:

◆ AddBinaryOperator()

◆ AddNamed()

◆ AddType()

◆ AddUnaryOperator()

◆ Compile()

◆ GetBinaryOperatorPrecedence()

◆ getCompileTimeScope()

◆ GetNamed()

◆ getOptimizedExpressionString()

◆ RemoveNamed()

◆ SetupDefaults()

◆ TypeName()

◆ WriteFunctionSignature() [1/2]

◆ WriteFunctionSignature() [2/2]