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 ExpressionVal

Definition at line 68 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) , IF_ALIB_CAMP }

using	Plugins = std::vector<lang::PluginContainer<CompilerPlugin, CompilePriorities>::Slot>
	Alias shortcut to the type of the plug-in vector inherited from PluginContainer.

Public Type Index: inherited from PluginContainer< CompilerPlugin, CompilePriorities >
using	PluginType
	This exposes the template parameter pTPlugin to the outer world.

using	PrioritiesType
	This exposes the template parameter pTPlugin to the outer world.

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

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

HashMap< MonoAllocator, String, int >	BinaryOperators

BuiltInPlugins	CfgBuiltInPlugins = BuiltInPlugins::ALL

Compilation	CfgCompilation = Compilation::DEFAULT
	Compilation flags.

SPFormatter	CfgFormatter

strings::util::Token	CfgNestedExpressionFunction

String	CfgNestedExpressionOperator = A_CHAR("*")

String	CfgNestedExpressionThrowIdentifier

Normalization	CfgNormalization = Normalization::DEFAULT

StringVectorMA	CfgNormalizationDisallowed

ExpressionRepository *	Repository = nullptr

List< MonoAllocator, String >	UnaryOperators

Public Method Index:
ALIB_API	Compiler ()

virtual ALIB_API	~Compiler ()
	Destructor.

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 Expression	Compile (const String &expressionString)

MonoAllocator &	GetAllocator ()

int	GetBinaryOperatorPrecedence (const String &symbol)

virtual ALIB_API Expression	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 ()

CompilerPlugin *	GetPlugin (CompilePriorities priority)

CompilerPlugin *	GetPlugin (integer number)

TPluginType *	GetPluginTypeSafe ()

TPluginType *	GetPluginTypeSafe (CompilePriorities priority)

CompilePriorities	GetPriority (integer number)

bool	HasPlugins ()

void	InsertPlugin (CompilerPlugin *plugin, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)

CompilerPlugin *	RemovePlugin (CompilePriorities priority)

bool	RemovePlugin (CompilerPlugin *plugIn)

void	RemovePlugin (integer idx)

Protected Field Index:
MonoAllocator	allocator

HashMap< MonoAllocator, AString, Expression, std::hash< String >, std::equal_to< String > >	namedExpressions
	The map of 'named' expressions.

detail::Parser *	parser = nullptr
	The expression parser.

HashMap< MonoAllocator, TypeFunctors::Key, NAString, TypeFunctors::Hash, TypeFunctors::EqualTo >	typeMap
	The map of Type names and bit flag values.

Protected Field Index: inherited from PluginContainer< CompilerPlugin, CompilePriorities >
std::vector< Slot >	plugins
	The plug-ins we have attached in descending priority order.

Protected Method Index:
virtual ALIB_API Scope *	createCompileTimeScope (MonoAllocator &expressionAllocator)

ALIB_API void	getOptimizedExpressionString (ExpressionVal &expression)

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 78 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.
IF_ALIB_CAMP	Installs plugins::DateAndTime. )

Definition at line 213 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 87 of file compiler.hpp.

◆ AlphabeticBinaryOperatorAliases

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

This public map allows defining 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 142 of file compiler.hpp.

◆ AlphabeticUnaryOperatorAliases

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

This public map allows defining 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 132 of file compiler.hpp.

◆ BinaryOperators

HashMap<MonoAllocator, String, int> BinaryOperators

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

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

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

Definition at line 169 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 239 of file compiler.hpp.

◆ CfgCompilation

Compilation CfgCompilation = Compilation::DEFAULT

Compilation flags.

Definition at line 273 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 {lang::format::Formatter;Default;default formatter} is copied here.

Definition at line 316 of file compiler.hpp.

◆ CfgNestedExpressionFunction

strings::util::Token CfgNestedExpressionFunction

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

See also: Manual chapter 10. Nested Expressions.

Definition at line 264 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 before 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 256 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 270 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 277 of file compiler.hpp.

◆ CfgNormalizationDisallowed

StringVectorMA 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 298 of file compiler.hpp.

◆ namedExpressions

HashMap< MonoAllocator, AString, Expression, std::hash <String>, std::equal_to<String> > namedExpressions

protected

The map of 'named' expressions.

Definition at line 102 of file compiler.hpp.

◆ parser

detail::Parser* parser = nullptr

protected

The expression parser.

Definition at line 90 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 322 of file compiler.hpp.

◆ typeMap

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

protected

The map of Type names and bit flag values.

Definition at line 96 of file compiler.hpp.

◆ UnaryOperators

List<MonoAllocator, 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 121 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 108 of file compiler.cpp.

Here is the call graph for this function:

◆ ~Compiler()

~Compiler ( )

virtual

Destructor.

Definition at line 151 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 before invoking SetupDefaults.

Operator symbols must be added only once.

Parameters

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

Definition at line 178 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 358 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 426 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 before invoking SetupDefaults.

Operator symbols must be added only once.

Parameters

symbol The operator symbol.

Definition at line 150 of file compiler.hpp.

◆ Compile()

Expression 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 ExpressionVal::GetOriginalString, the normalized version can be retrieved after the compilation with method ExpressionVal::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 createCompileTimeScope. 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 createCompileTimeScope accordingly.

Parameters

expressionString The string to parse.

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

Definition at line 242 of file compiler.cpp.

Here is the call graph for this function:

◆ createCompileTimeScope()

Scope * createCompileTimeScope ( MonoAllocator & expressionAllocator )

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 a custom scope object.

Parameters

expressionAllocator The allocator of the expression used to allocate the compile-time scope.

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

Definition at line 157 of file compiler.cpp.

◆ GetAllocator()

MonoAllocator & GetAllocator ( )

inline

Provides access to the internal MonoAllocator.

Note: This method is deemed non-standard use of this class and the using code needs to knowing what to do.

Returns: The internal monotonous allocator.

Definition at line 512 of file compiler.hpp.

◆ 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 190 of file compiler.hpp.

◆ GetNamed()

Expression GetNamed ( const String & name )

virtual

Returns a named expression previously defined using AddNamed. In the case that no expression with the given name 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 392 of file compiler.cpp.

Here is the call graph for this function:

◆ getOptimizedExpressionString()

void getOptimizedExpressionString ( ExpressionVal & expression )

protected

Implements ExpressionVal::GetOptimizedString.

Parameters

expression the expression to generate an optimized string for.

Definition at line 330 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 488 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 163 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 434 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 476 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 450 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:

Protected Field Index:

Protected 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()

◆ createCompileTimeScope()

◆ GetAllocator()

◆ GetBinaryOperatorPrecedence()

◆ GetNamed()

◆ getOptimizedExpressionString()

◆ RemoveNamed()

◆ SetupDefaults()

◆ TypeName()

◆ WriteFunctionSignature() [1/2]

◆ WriteFunctionSignature() [2/2]