tpsystools_4.04/source/StExpr.txt


This file documents the TStExpression and TStExpressionEdit components.


TStExpression
=============

TStExpression is a non-visual component that provides expression evaluation
at several different levels. At the lowest level, simple mathematical
expressions can be evaluated and the resulting value obtained. On a higher
level, you can define alpha-numeric constants that can then be used within
expressions; You can add user-defined functions (and even methods of a class)
so that the names of these routines can be used in expressions; You can
define variables that relate directly to variables in your program and even
use them in expressions.

Note: TStExpression replaces AnalyzeExpr that SysTools version 2.00 provided,
but a version of that routine is still provided for backward compatibility.

The TStExpression expression parser implements the following grammar, similar
to a subset of Pascal:

   expression:    term | expression+term | expression-term
   term:          factor | term*factor | term/factor
   factor:        base | base^factor
   base:          unsigned_num | (expression) | sign factor | func_call
   unsigned_num:  digit_seq | digit_seq.digit_seq | digit_seq scale_fac |
                  digit_seq.digit_seq scale_fac
   sign:          + | -
   func_call:     identifier | identifier(params)
   params:        expression | params,expression
   scale_fac:     E digit_seq | E sign digit_seq
   digit_seq:     digit | digit_seq digit
   identifier:    starts with A..Z,_ continues with A..Z,_,0..9
   digit:         0..9

Case is not significant when matching characters.

The grammar follows normal rules of arithmetic precedence, with ^ highest, *
and / in the middle, and + and - lowest.  Thus, 1+2*3^4 means 1+(2*(3^4)).
Parentheses can be used to force non-default precedence.

Note that the power operator x^y is right-associative. This means that
2^0.5^2 is equivalent to 2^(0.5^2). All other arithmetic operators are left
associative: 1-2-3 is equivalent to (1-2)-3.

The following functions are supported in 16-bit and 32-bit applications:

    abs, arctan, cos, exp, frac, int(trunc), ln, pi, round, sin, sqr,
    sqrt

If the VCL Math unit is available and you define the "UseMathUnit" define in
STDEFINE.INC, the following are also available:

    arccos, arcsin, arctan2, tan, cotan, hypot, cosh, sinh, tanh,
    arccosh, arcsinh, arctanh, lnxp1, log10, log2, logn, ceil, floor

The calling conventions for all functions match those of the VCL runtime
library or Math unit. The acceptable parameter ranges and output values also
match thoses of the VCL runtime library or MATH unit.

When the input expression contains an error, TStExpression raises an
exception of type EStExprError. Its ErrorCode property provides more detail
about the error. Its ErrorColumn property gives the string index of the start
of the token where the error was detected.

TStExpression is very flexible. You can add support for your own functions
easily. For example, to add support for the Sin() function, first write a
function to provide the proper number and type of parameters (the "far" can
be omitted with 32-bit compilers):

function _Sin(Value : TStFloat) : TStFloat; far;
begin
  Result := Sin(Value);
end;

and then add it to the TStExpression component:

   MyStExpression.AddFunction1Param('sin', _Sin);

Or, if you wanted to use a method of the form (or any other class) that you
were working in, you could do the same thing this way:

function MyForm._Sin(Value : TStFloat) : TStFloat;
begin
  Result := Sin(Value);
end;

and then add it to the TStExpression component:

  MyStExpression.AddMethod1Param('sin', _Sin);

TStExpression supports user-defined functions with 0 to 3 parameters. The
parameters and function result must be the TStFloat type (defined in the
STBASE unit). In the example above, that's why we didn't just add
the Sin() function directly, in the call to AddFunction1Param -- The
TStExpression component must know the data types of parameters and return
values. If the function you are adding has no parameters, use the
AddFunction0Parm() method. AddFunction2Param for functions with two
parameters, etc.

The following function and method types define all possible user-defined
function and method types accepted by the TStExpression component:

  {user-defined functions with up to 3 parameters}
  TStFunction0Param =
    function : TStFloat;
  TStFunction1Param =
    function(Value1 : TStFloat) : TStFloat;
  TStFunction2Param =
    function(Value1, Value2 : TStFloat) : TStFloat;
  TStFunction3Param =
    function(Value1, Value2, Value3 : TStFloat) : TStFloat;

  {user-defined methods with up to 3 parameters}
  TStMethod0Param =
    function : TStFloat
    of object;
  TStMethod1Param =
    function(Value1 : TStFloat) : TStFloat
    of object;
  TStMethod2Param =
    function(Value1, Value2 : TStFloat) : TStFloat
    of object;
  TStMethod3Param =
    function(Value1, Value2, Value3 : TStFloat) : TStFloat
    of object;

Add predefined constant values by using the AddConstant method:

  AddConstant('X', 50)

Then, in any expression that uses the identifier "X", the value 50 will be
used when the expression is evaluated.

Add references to variables in your program by using the AddVariable method:

  var
    MyVar : TStFloat;

  AddVariable('MyVar', @MyVar);

Whenever an expression is evaluated that contains the "MyVar" identifier,
the actual value of the variable (in your program) is retrieved and used
to compute the expression result. Changes to variable's value in your
program will be reflected when the expression is next evaluated.

Two things to note: First, the variable must be a TStFloat type and second,
the variable must remain in "scope". In general, this means that the variable
must either be defined globally or as a class variable. You normally would not
use AddVariable for variables defined local to a procedure or function (a
stack variable).

TStExpression offers a way to dynamically determine the value of an variable
or function that is being used in an expression -- the OnGetIdentValue event.
This event is fired if the expression parser is unable to locate the identifier
in its internal list of identifier names. In response to the event, you should
assign a value to the Value parameter that corresponds to the identifier name
passed to the event as the Identifier parameter. If no event handler is
assigned to this even and the expression parser is unable to locate a match for
an identifier used in an expression, an exception is raised.


Reference Section
-----------------

methods
-------

function AnalyzeExpression : TStFloat;
-> AnalyzeExpression causes the expression contained in the Expression property
   to be evaluated and returns the resulting value as the function result.


procedure AddConstant(const Name : string; Value : TStFloat);
-> AddConstant adds named constant values for use within expressions.

Example: AddConstant('X', 50)


procedure AddFunction0Param(const Name : string; FunctionAddr : TStFunction0Param);
procedure AddFunction1Param(const Name : string; FunctionAddr : TStFunction1Param);
procedure AddFunction2Param(const Name : string; FunctionAddr : TStFunction2Param);
procedure AddFunction3Param(const Name : string; FunctionAddr : TStFunction3Param);
-> AddFunctionXParam adds support for user-defined functions within expressions.

The four variations allow defining functions with no parameters, or, with one,
two, or three parameters. Name is the identifier that is entered into the
expression. The name does not need to be the same as the actual function name.

Parameter and function results must be defined as TStFloat.


procedure AddInternalFunctions;
-> AddInternalFunctions adds support for all of the predefined internal
   functions.

Since AddInternalFunctions is called by default, calling this routine without
first calling ClearIdentifiers will result in duplicate identifier exceptions.


procedure AddMethod0Param(const Name : string; MethodAddr : TStMethod0Param);
procedure AddMethod1Param(const Name : string; MethodAddr : TStMethod1Param);
procedure AddMethod2Param(const Name : string; MethodAddr : TStMethod2Param);
procedure AddMethod3Param(const Name : string; MethodAddr : TStMethod3Param);
-> AddMethodXParam adds support for user-defined methods within expressions.

The four variations allow defining methods with no parameters, or, with one,
two, or three parameters. Name is the identifier that is entered into the
expression. The name does not need to be the same as the actual method name.

Parameter and function results must be defined as TStFloat.


procedure AddVariable(const Name : string; VariableAddr : PStFloat);
-> Adds Name as a reference to a variable in your program.

Name is the identifier used in expressions.

Example:

  var
    X : TStFloat;
  ...
  AddVariable('X', @X)


procedure ClearIdentifiers;
-> ClearIdentifiers removes all function, method, constant, and variable identifiers.


procedure GetIdentList(S : TStrings);
-> GetIdentList fills S with a list of identifiers current recognized.


procedure RemoveIdentifier(const Name : string);
-> RemoveIdentifier removes support for the identifier Name.

If Name is not found, no action is taken.


properties
----------
property AsFloat : TStFloat (run-time read-only)
-> AsFloat evaluates the expression and returns the value as a TStFloat
   value;

property AsInteger : Integer (run-time read-only)
-> AsInteger evaluates the expression and returns the value as a whole number
   using the Round() function to convert the TStFloat value.

property AsString : string (run-time read-only)
-> AsString evaluates the expression and returns the value as a string using
   the FloatToStr() function to format the TStFloat value.

property LastError : Integer (run-time read-only)
-> LastError returns the error code (zero if no error).

property ErrorPosition : Integer (run-time read-only)
-> ErrorPosition returns the position of the error within the expression.

ErrorPosition is valid only if LastError is non-zero.

property Expression : string (run-time)
-> Expression defines the expression that should be evaluated.

property AllowEqual : Boolean
default: True
-> AllowEqual determines if the use of the "=" symbol in the expression will
   add constant declarations.

If true, expressions like X = 5 will cause the identifer "X" to be added and
associated with the value 5. This expression will also return a value of 5
when analyzed. If false, a bad character exception is raised.


events
------
property OnAddIdentifier : TNotifyEvent
-> OnAddIdentifier defines an event that is fired when a new identifier
   is added.

This event is fired for additions of function, method, constant, and variable
identifiers.

property OnGetIdentValue : TGetIdentValueEvent
TGetIdentValueEvent =
  procedure(Sender : TObject; const Identifier : string; var Value : TStFloat)
  of object;
-> OnGetIdentValue defines an event handler that is fired to obtain the value
for an identifier that was not found in the internal list of known identifiers.


TStExpressionEdit
=================
The TStExpressionEdit component is a simple descendant of a TEdit component
that adds one new method, two properties, and two new events.  In all other
respects, this control is the same as the standard VCL TEdit control.

The TStExpressionEdit uses an instance of the TStExpression component to do
most of the work. Any expression that is valid for the TStExpression
component can be entered into the component or assigned to the Text property.
The expression is evaluated when the component loses the focus (with AutoEval
true) or when the Evaluate method is called. Also, if AutoEval is true and
the control loses the focus, the resulting value is displayed in the control.


New properties and methods:

function Evaluate : TStFloat;

-> Evaluate evaluates the contents of the Text property as an expression
using the contained TStExpression component and returns the result of the
expression as the function result.

If an error occurs an exception is raised unless an event handler for the
OnError event is assigned. In which case, the event is fired instead.

Note: The AnalyzeExpr function (which is documented in the printed
manual and on-line help) is obsolete and is provided for backward
compatibility only.


property AutoEval : Boolean

-> AutoEval determines if the entered expression is automatically evaluated
   when the control loses the focus.

If AutoEval is true, the Evaluate method is called automatically and the
Text of the edit control is set to the result of evaluating the expression.
If False, no additional action is taken.


property Expr : TStExpression (run-time)

-> Expr provides access to the contained TStExpression component and all of
   its properties, methods, and events.


property OnAddIdentifier : TNotifyEvent

-> OnAddIdentifier defines an event that is fired when an identifier is
   added to the internal TStExpression component.

This event is fired to notify you that a constant or function identifier has
been added to the contained TStExpression component.


property OnError : TStExprErrorEvent

  TStExprErrorEvent =
    procedure(Sender : TObject; ErrorNumber : LongInt; const ErrorStr : string)
    of object;

-> OnError defines an event that is fired when an evaluation error occurs.
1
2	This file documents the TStExpression and TStExpressionEdit components.
3
4
5	TStExpression
6	=============
7
8	TStExpression is a non-visual component that provides expression evaluation
9	at several different levels. At the lowest level, simple mathematical
10	expressions can be evaluated and the resulting value obtained. On a higher
11	level, you can define alpha-numeric constants that can then be used within
12	expressions; You can add user-defined functions (and even methods of a class)
13	so that the names of these routines can be used in expressions; You can
14	define variables that relate directly to variables in your program and even
15	use them in expressions.
16
17	Note: TStExpression replaces AnalyzeExpr that SysTools version 2.00 provided,
18	but a version of that routine is still provided for backward compatibility.
19
20	The TStExpression expression parser implements the following grammar, similar
21	to a subset of Pascal:
22
23	expression: term \| expression+term \| expression-term
24	term: factor \| term*factor \| term/factor
25	factor: base \| base^factor
26	base: unsigned_num \| (expression) \| sign factor \| func_call
27	unsigned_num: digit_seq \| digit_seq.digit_seq \| digit_seq scale_fac \|
28	digit_seq.digit_seq scale_fac
29	sign: + \| -
30	func_call: identifier \| identifier(params)
31	params: expression \| params,expression
32	scale_fac: E digit_seq \| E sign digit_seq
33	digit_seq: digit \| digit_seq digit
34	identifier: starts with A..Z,_ continues with A..Z,_,0..9
35	digit: 0..9
36
37	Case is not significant when matching characters.
38
39	The grammar follows normal rules of arithmetic precedence, with ^ highest, *
40	and / in the middle, and + and - lowest. Thus, 1+23^4 means 1+(2(3^4)).
41	Parentheses can be used to force non-default precedence.
42
43	Note that the power operator x^y is right-associative. This means that
44	2^0.5^2 is equivalent to 2^(0.5^2). All other arithmetic operators are left
45	associative: 1-2-3 is equivalent to (1-2)-3.
46
47	The following functions are supported in 16-bit and 32-bit applications:
48
49	abs, arctan, cos, exp, frac, int(trunc), ln, pi, round, sin, sqr,
50	sqrt
51
52	If the VCL Math unit is available and you define the "UseMathUnit" define in
53	STDEFINE.INC, the following are also available:
54
55	arccos, arcsin, arctan2, tan, cotan, hypot, cosh, sinh, tanh,
56	arccosh, arcsinh, arctanh, lnxp1, log10, log2, logn, ceil, floor
57
58	The calling conventions for all functions match those of the VCL runtime
59	library or Math unit. The acceptable parameter ranges and output values also
60	match thoses of the VCL runtime library or MATH unit.
61
62	When the input expression contains an error, TStExpression raises an
63	exception of type EStExprError. Its ErrorCode property provides more detail
64	about the error. Its ErrorColumn property gives the string index of the start
65	of the token where the error was detected.
66
67	TStExpression is very flexible. You can add support for your own functions
68	easily. For example, to add support for the Sin() function, first write a
69	function to provide the proper number and type of parameters (the "far" can
70	be omitted with 32-bit compilers):
71
72	function _Sin(Value : TStFloat) : TStFloat; far;
73	begin
74	Result := Sin(Value);
75	end;
76
77	and then add it to the TStExpression component:
78
79	MyStExpression.AddFunction1Param('sin', _Sin);
80
81	Or, if you wanted to use a method of the form (or any other class) that you
82	were working in, you could do the same thing this way:
83
84	function MyForm._Sin(Value : TStFloat) : TStFloat;
85	begin
86	Result := Sin(Value);
87	end;
88
89	and then add it to the TStExpression component:
90
91	MyStExpression.AddMethod1Param('sin', _Sin);
92
93	TStExpression supports user-defined functions with 0 to 3 parameters. The
94	parameters and function result must be the TStFloat type (defined in the
95	STBASE unit). In the example above, that's why we didn't just add
96	the Sin() function directly, in the call to AddFunction1Param -- The
97	TStExpression component must know the data types of parameters and return
98	values. If the function you are adding has no parameters, use the
99	AddFunction0Parm() method. AddFunction2Param for functions with two
100	parameters, etc.
101
102	The following function and method types define all possible user-defined
103	function and method types accepted by the TStExpression component:
104
105	{user-defined functions with up to 3 parameters}
106	TStFunction0Param =
107	function : TStFloat;
108	TStFunction1Param =
109	function(Value1 : TStFloat) : TStFloat;
110	TStFunction2Param =
111	function(Value1, Value2 : TStFloat) : TStFloat;
112	TStFunction3Param =
113	function(Value1, Value2, Value3 : TStFloat) : TStFloat;
114
115	{user-defined methods with up to 3 parameters}
116	TStMethod0Param =
117	function : TStFloat
118	of object;
119	TStMethod1Param =
120	function(Value1 : TStFloat) : TStFloat
121	of object;
122	TStMethod2Param =
123	function(Value1, Value2 : TStFloat) : TStFloat
124	of object;
125	TStMethod3Param =
126	function(Value1, Value2, Value3 : TStFloat) : TStFloat
127	of object;
128
129	Add predefined constant values by using the AddConstant method:
130
131	AddConstant('X', 50)
132
133	Then, in any expression that uses the identifier "X", the value 50 will be
134	used when the expression is evaluated.
135
136	Add references to variables in your program by using the AddVariable method:
137
138	var
139	MyVar : TStFloat;
140
141	AddVariable('MyVar', @MyVar);
142
143	Whenever an expression is evaluated that contains the "MyVar" identifier,
144	the actual value of the variable (in your program) is retrieved and used
145	to compute the expression result. Changes to variable's value in your
146	program will be reflected when the expression is next evaluated.
147
148	Two things to note: First, the variable must be a TStFloat type and second,
149	the variable must remain in "scope". In general, this means that the variable
150	must either be defined globally or as a class variable. You normally would not
151	use AddVariable for variables defined local to a procedure or function (a
152	stack variable).
153
154	TStExpression offers a way to dynamically determine the value of an variable
155	or function that is being used in an expression -- the OnGetIdentValue event.
156	This event is fired if the expression parser is unable to locate the identifier
157	in its internal list of identifier names. In response to the event, you should
158	assign a value to the Value parameter that corresponds to the identifier name
159	passed to the event as the Identifier parameter. If no event handler is
160	assigned to this even and the expression parser is unable to locate a match for
161	an identifier used in an expression, an exception is raised.
162
163
164	Reference Section
165	-----------------
166
167	methods
168	-------
169
170	function AnalyzeExpression : TStFloat;
171	-> AnalyzeExpression causes the expression contained in the Expression property
172	to be evaluated and returns the resulting value as the function result.
173
174
175	procedure AddConstant(const Name : string; Value : TStFloat);
176	-> AddConstant adds named constant values for use within expressions.
177
178	Example: AddConstant('X', 50)
179
180
181	procedure AddFunction0Param(const Name : string; FunctionAddr : TStFunction0Param);
182	procedure AddFunction1Param(const Name : string; FunctionAddr : TStFunction1Param);
183	procedure AddFunction2Param(const Name : string; FunctionAddr : TStFunction2Param);
184	procedure AddFunction3Param(const Name : string; FunctionAddr : TStFunction3Param);
185	-> AddFunctionXParam adds support for user-defined functions within expressions.
186
187	The four variations allow defining functions with no parameters, or, with one,
188	two, or three parameters. Name is the identifier that is entered into the
189	expression. The name does not need to be the same as the actual function name.
190
191	Parameter and function results must be defined as TStFloat.
192
193
194	procedure AddInternalFunctions;
195	-> AddInternalFunctions adds support for all of the predefined internal
196	functions.
197
198	Since AddInternalFunctions is called by default, calling this routine without
199	first calling ClearIdentifiers will result in duplicate identifier exceptions.
200
201
202	procedure AddMethod0Param(const Name : string; MethodAddr : TStMethod0Param);
203	procedure AddMethod1Param(const Name : string; MethodAddr : TStMethod1Param);
204	procedure AddMethod2Param(const Name : string; MethodAddr : TStMethod2Param);
205	procedure AddMethod3Param(const Name : string; MethodAddr : TStMethod3Param);
206	-> AddMethodXParam adds support for user-defined methods within expressions.
207
208	The four variations allow defining methods with no parameters, or, with one,
209	two, or three parameters. Name is the identifier that is entered into the
210	expression. The name does not need to be the same as the actual method name.
211
212	Parameter and function results must be defined as TStFloat.
213
214
215	procedure AddVariable(const Name : string; VariableAddr : PStFloat);
216	-> Adds Name as a reference to a variable in your program.
217
218	Name is the identifier used in expressions.
219
220	Example:
221
222	var
223	X : TStFloat;
224	...
225	AddVariable('X', @X)
226
227
228	procedure ClearIdentifiers;
229	-> ClearIdentifiers removes all function, method, constant, and variable identifiers.
230
231
232	procedure GetIdentList(S : TStrings);
233	-> GetIdentList fills S with a list of identifiers current recognized.
234
235
236	procedure RemoveIdentifier(const Name : string);
237	-> RemoveIdentifier removes support for the identifier Name.
238
239	If Name is not found, no action is taken.
240
241
242	properties
243	----------
244	property AsFloat : TStFloat (run-time read-only)
245	-> AsFloat evaluates the expression and returns the value as a TStFloat
246	value;
247
248	property AsInteger : Integer (run-time read-only)
249	-> AsInteger evaluates the expression and returns the value as a whole number
250	using the Round() function to convert the TStFloat value.
251
252	property AsString : string (run-time read-only)
253	-> AsString evaluates the expression and returns the value as a string using
254	the FloatToStr() function to format the TStFloat value.
255
256	property LastError : Integer (run-time read-only)
257	-> LastError returns the error code (zero if no error).
258
259	property ErrorPosition : Integer (run-time read-only)
260	-> ErrorPosition returns the position of the error within the expression.
261
262	ErrorPosition is valid only if LastError is non-zero.
263
264	property Expression : string (run-time)
265	-> Expression defines the expression that should be evaluated.
266
267	property AllowEqual : Boolean
268	default: True
269	-> AllowEqual determines if the use of the "=" symbol in the expression will
270	add constant declarations.
271
272	If true, expressions like X = 5 will cause the identifer "X" to be added and
273	associated with the value 5. This expression will also return a value of 5
274	when analyzed. If false, a bad character exception is raised.
275
276
277	events
278	------
279	property OnAddIdentifier : TNotifyEvent
280	-> OnAddIdentifier defines an event that is fired when a new identifier
281	is added.
282
283	This event is fired for additions of function, method, constant, and variable
284	identifiers.
285
286	property OnGetIdentValue : TGetIdentValueEvent
287	TGetIdentValueEvent =
288	procedure(Sender : TObject; const Identifier : string; var Value : TStFloat)
289	of object;
290	-> OnGetIdentValue defines an event handler that is fired to obtain the value
291	for an identifier that was not found in the internal list of known identifiers.
292
293
294	TStExpressionEdit
295	=================
296	The TStExpressionEdit component is a simple descendant of a TEdit component
297	that adds one new method, two properties, and two new events. In all other
298	respects, this control is the same as the standard VCL TEdit control.
299
300	The TStExpressionEdit uses an instance of the TStExpression component to do
301	most of the work. Any expression that is valid for the TStExpression
302	component can be entered into the component or assigned to the Text property.
303	The expression is evaluated when the component loses the focus (with AutoEval
304	true) or when the Evaluate method is called. Also, if AutoEval is true and
305	the control loses the focus, the resulting value is displayed in the control.
306
307
308	New properties and methods:
309
310	function Evaluate : TStFloat;
311
312	-> Evaluate evaluates the contents of the Text property as an expression
313	using the contained TStExpression component and returns the result of the
314	expression as the function result.
315
316	If an error occurs an exception is raised unless an event handler for the
317	OnError event is assigned. In which case, the event is fired instead.
318
319	Note: The AnalyzeExpr function (which is documented in the printed
320	manual and on-line help) is obsolete and is provided for backward
321	compatibility only.
322
323
324	property AutoEval : Boolean
325
326	-> AutoEval determines if the entered expression is automatically evaluated
327	when the control loses the focus.
328
329	If AutoEval is true, the Evaluate method is called automatically and the
330	Text of the edit control is set to the result of evaluating the expression.
331	If False, no additional action is taken.
332
333
334	property Expr : TStExpression (run-time)
335
336	-> Expr provides access to the contained TStExpression component and all of
337	its properties, methods, and events.
338
339
340	property OnAddIdentifier : TNotifyEvent
341
342	-> OnAddIdentifier defines an event that is fired when an identifier is
343	added to the internal TStExpression component.
344
345	This event is fired to notify you that a constant or function identifier has
346	been added to the contained TStExpression component.
347
348
349	property OnError : TStExprErrorEvent
350
351	TStExprErrorEvent =
352	procedure(Sender : TObject; ErrorNumber : LongInt; const ErrorStr : string)
353	of object;
354
355	-> OnError defines an event that is fired when an evaluation error occurs.