ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
program.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_expressions of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib { namespace expressions {
9
10/// This is the detail namespace of #alib::expressions implementing the abstract syntax tree,
11/// the expression parser, the expression program and the virtual machine to execute the program
12/// with expression evaluation.
13namespace detail {
14
15
16//==================================================================================================
17/// This class represents a program that is "run on" the \alib{expressions;detail::VirtualMachine}
18/// to evaluate an expression.
19///
20/// ## Friends ##
21/// class \alib{expressions;detail::VirtualMachine}
22//==================================================================================================
23class Program : public ProgramBase
24{
25 // #############################################################################################
26 // Public fields
27 // #############################################################################################
28 public:
29 /// The compiler that created this object.
31
32 /// The expression that this program evaluates.
34
35
36 // #############################################################################################
37 // Internal fields
38 // #############################################################################################
39 protected:
40 /// Shortcut.
42
43 /// The array of commands.
45
46 /// The number of commands.
48
49 /// List of compile-time identified nested expressions. Using the shared pointers, it is
50 /// ensured that the expressions do not get deleted until this program is.
52
53 /// Counter of the number of optimization made during program assembly.
55
56 /// Data needed during compilation. An instance of this object is allocated
57 /// in the temporary compile-time monotonic allocator.
59 {
60 /// The intermediate program listing. Commands are collected here during
61 /// compilation. Only when finalized, the result is copied into the vector that
62 /// the outer class program inherits from, which uses the non-temporary monotonic
63 /// allocator.
65
66 /// Used with compilation. Stores the positions of current result types while adding new
67 /// commands.
69
70 /// Compile-time information on conditional operator jump positions.
72 {
73 #if !DOXYGEN
74 ConditionalInfo( VM::PC q, VM::PC t, int f)
75 : QJumpPos (q)
76 , TJumpPos (t)
77 , ConstFlags(f)
78 {}
79 #endif
80
81 VM::PC QJumpPos; ///< The position of the lhs result.
82 VM::PC TJumpPos; ///< The position of the jump command between T and F.
83 int ConstFlags; ///< Two bits: Bit 1 determines whether Q was constant and
84 ///< bit 0 stores the value of Q (if constant)
85 };
86
87 /// Stores the positions of current results while adding new commands.
88 /// The third value is used for optimizing constant conditionals out.
90
91 /// Needed during compilation. Collects information from plug-ins to create meaningful
92 /// messages.
94
95 /// Constructor.<br>
96 /// The given allocator is used exclusively during compilation.
97 /// Its memory is cleared (respectively reset to a previous state) after the
98 /// compilation completed. The program is created in this allocator. Only when
99 /// compilation is finished (and after all optimizations have been performed)
100 /// it is copied to the compile-time scope's allocator.<br>
101 /// (Refers to object \alib{expressions;Compiler::allocator}.)
102 ///
103 /// @param compileTimeAllocator The allocator to use temporarily during compilation.
104 CompileStorage( MonoAllocator& compileTimeAllocator )
105 : Assembly (compileTimeAllocator)
106 , ResultStack (compileTimeAllocator)
107 , ConditionalStack (compileTimeAllocator)
108 , FunctionsWithNonMatchingArguments(compileTimeAllocator)
109 {
110 Assembly .reserve(30);
111 ResultStack .reserve(20);
112 ConditionalStack.reserve(5);
113 }
114
115 };
116
117 /// Set of data needed during compilation and deleted afterwards. Also, this field indicates
118 /// that compilation is "suppressed", which is used when normalized optimized expression
119 /// strings are generated from de-compiled programs.
121
122
123 // #############################################################################################
124 // Constructor/destructor
125 // ##################################################P###########################################
126 public:
127 /// Constructor.
128 ///
129 /// Prepares the assembly if \p{compileTimeAlloc} is given. If it is \c nullptr, then no
130 /// program is assembled. This option is used for creating normalized expression strings from
131 /// de-compiled, optimized programs.
132 ///
133 /// @param pCompiler Stored in field #compiler.
134 /// @param pExpression Stored in field #expression.
135 /// @param ctAlloc A temporary allocator valid until assembly of the program
136 /// finished.<br>
137 /// If \c nullptr, no assembly is performed in later invocations
138 /// of assemble methods.
139 /// This option is used for the generation of normalized, optimized
140 /// expression strings. from reversely created ASTs.
142 Program( Compiler& pCompiler, ExpressionVal& pExpression, MonoAllocator* ctAlloc );
143
144 /// Destructor.
146
147 // #############################################################################################
148 // Overrides
149 // #############################################################################################
150 /// Returns the result type of the program.
151 /// @return The program's result type.
153 const Box& ResultType() const
154 {
155 return commands[commandsCount-1].ResultType;
156 }
157
158
159 /// Returns the number of \alib{expressions::detail;VirtualMachine::Command} that the
160 /// program encompasses.
161 /// @return The program's length.
162 integer Length() const { return commandsCount; }
163
164 /// Returns the command at the given program counter \p{pc}.
165 /// @param pc The program counter of the command to get.
166 /// @return A reference to the requested command.
168 {
169 return commands[pc];
170 }
171
172 /// @return The number of optimizations or \c -1 if optimizations were not activated during
173 /// program assembly.
175 {
176 return qtyOptimizations;
177 }
178
179 /// Runs the program using the virtual machine.
180 ///
181 /// @param scope The evaluation scope.
182 /// @return The result value.
183 Box Run(Scope& scope)
184 {
185 return VirtualMachine::Run(*this, scope);
186 }
187
188
189 // #############################################################################################
190 // Assemble methods
191 // #############################################################################################
192
193 /// Has to be invoked to finalizes the program after.
194 /// No further invocations of assemble methods must be invoked after a call to this method.
196 void AssembleFinalize();
197
198
199 /// Add a command that produces a constant value. Used with literals.
200 /// @param value The value to produce.
201 /// @param idxInOriginal The index of the operator in the expression string.
202 /// @param idxInNormalized The index of the operator in the normalized expression
203 /// string.
205 void AssembleConstant( Box& value,
206 integer idxInOriginal, integer idxInNormalized );
207
208 /// Add a command that invokes a native function.
209 /// @param functionName The name of the function.
210 /// Used to query the corresponding native C++ callback
211 /// function from the compiler plug-ins.
212 /// @param idxInOriginal The index of the operator in the expression string.
213 /// @param idxInNormalized The index of the operator in the normalized expression
214 /// string.
215 /// @param isIdentifier To be \c true, if no parentheses were given. In this case,
216 /// was given as an 'identifier', what
217 /// means that no brackets '()' had been added.
218 /// @param qtyArgs The number of function args. If negative, this indicates
219 /// that the function name was given as an 'identifier', what
220 /// means that no brackets '()' had been added.
222 void AssembleFunction( AString& functionName, bool isIdentifier, int qtyArgs,
223 integer idxInOriginal, integer idxInNormalized );
224
225 /// Add a command that invokes a native function that implements an unary operator.
226 /// @param op The operator to add a command for.
227 /// @param idxInOriginal The index of the operator in the expression string.
228 /// @param idxInNormalized The index of the operator in the normalized expression string.
230 void AssembleUnaryOp( String& op, integer idxInOriginal, integer idxInNormalized );
231
232 /// Add a command that invokes a native function that implements a binary operator.
233 /// @param op The operator to add a command for.
234 /// @param idxInOriginal The index of the operator in the expression string.
235 /// @param idxInNormalized The index of the operator in the normalized expression string.
237 void AssembleBinaryOp( String& op, integer idxInOriginal, integer idxInNormalized );
238
239 /// To be called after the AST for \c Q was assembled. Adds an "jump on false" statement,
240 /// unless it is detected that \c Q is constant. In this case, only one of the subsequent
241 /// sub-expressions is assembled.
242 ///
243 /// Has to be followed by assembly of \c T, followed by
244 /// #AssembleCondFinalize_T and furthermore assembly of \c F, followed by
245 /// #AssembleCondFinalize_F.
246 ///
247 /// @param idxInOriginal The index of the operator in the expression string.
248 /// @param idxInNormalized The index of the operator in the normalized expression string.
250 void AssembleCondFinalize_Q( integer idxInOriginal, integer idxInNormalized );
251
252 /// End of ternary \c T expression. Jumps to end of \c f.
253 /// @param idxInOriginal The index of the operator in the expression string.
254 /// @param idxInNormalized The index of the operator in the normalized expression string.
256 void AssembleCondFinalize_T( integer idxInOriginal, integer idxInNormalized );
257
258 /// Finalizes a previously started conditional expression.
259 /// @param idxInOriginal The index of the operator in the expression string.
260 /// @param idxInNormalized The index of the operator in the normalized expression string.
262 void AssembleCondFinalize_F( integer idxInOriginal, integer idxInNormalized );
263
264 // #############################################################################################
265 // Internals used during compilation
266 // #############################################################################################
267 protected:
268 /// Collects \p{qty} types from the result stack and stores them, respectively the constant
269 /// values in field \doxlinkproblem{structalib_1_1expressions_1_1Scope.html;af1f402e9cac81ef3ad0a982590344472;Scope::Stack;expressions::Scope::Stack}
270 /// stack of field \alib{expressions;ExpressionVal::ctScope}.
271 /// @param qty The number of types to collect.
272 /// @return \c true if all arguments collected were constants.
274 bool collectArgs( integer qty );
275
276};
277
278}}} // namespace [alib::expressions::detail]
279
Base class exported by the main module ALib.Expressions.H for technical reasons.
Definition compiler.inl:540
ExpressionVal & expression
The expression that this program evaluates.
Definition program.inl:33
ALIB_DLL void AssembleUnaryOp(String &op, integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:441
int qtyOptimizations
Counter of the number of optimization made during program assembly.
Definition program.inl:54
StdVectorMono< Expression > ctNestedExpressions
Definition program.inl:51
VirtualMachine VM
Shortcut.
Definition program.inl:41
ALIB_DLL const Box & ResultType() const
Definition program.inl:153
ALIB_DLL void AssembleFunction(AString &functionName, bool isIdentifier, int qtyArgs, integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:249
ALIB_DLL void AssembleBinaryOp(String &op, integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:625
ALIB_DLL void AssembleCondFinalize_Q(integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:832
ALIB_DLL Program(Compiler &pCompiler, ExpressionVal &pExpression, MonoAllocator *ctAlloc)
Definition program.cpp:47
VM::Command & At(VM::PC pc)
Definition program.inl:167
ALIB_DLL void AssembleConstant(Box &value, integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:234
Compiler & compiler
The compiler that created this object.
Definition program.inl:30
ALIB_DLL void AssembleCondFinalize_F(integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:885
ALIB_DLL ~Program()
Destructor.
Definition program.cpp:56
ALIB_DLL bool collectArgs(integer qty)
Definition program.cpp:211
integer commandsCount
The number of commands.
Definition program.inl:47
VM::Command * commands
The array of commands.
Definition program.inl:44
ALIB_DLL void AssembleCondFinalize_T(integer idxInOriginal, integer idxInNormalized)
Definition program.cpp:863
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
std::vector< T, SCAMono< T > > StdVectorMono
Type alias in namespace alib.
lang::integer integer
Type alias in namespace alib.
Definition integers.inl:149
monomem::TMonoAllocator< lang::HeapAllocator > MonoAllocator
boxing::Box Box
Type alias in namespace alib.
Definition box.inl:1216
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
containers::List< TAllocator, T, TRecycling > List
Type alias in namespace alib.
Definition list.inl:746
Compile-time information on conditional operator jump positions.
Definition program.inl:72
VM::PC TJumpPos
The position of the jump command between T and F.
Definition program.inl:82
StdVectorMono< VirtualMachine::Command * > Assembly
Definition program.inl:64
CompileStorage(MonoAllocator &compileTimeAllocator)
Definition program.inl:104
List< MonoAllocator, String > FunctionsWithNonMatchingArguments
Definition program.inl:93
StdVectorMono< ConditionalInfo > ConditionalStack
Definition program.inl:89
static ALIB_DLL alib::Box Run(Program &program, Scope &scope)
integer PC
Type definition for a program counter.