artformula.html

ArtFormula package contains two nonvisual Delphi component for symbolic expression parsing and evalu

<p><b>TArtFormula</b> has <b>AddUserFunction</b>
and <b>AddModuleFunction</b> procedures allow you to add user defined functions
and modules. <b>AddUserFunction</b> takes three or four parameters: function
name, number of parameters, pointer to corresponded Delphi function and flag
whether function is main function of new module. 

<p>First you should write Delphi function of next type: 

<p>function MyFunction(var Calc : TFormulaCalc):TCalcItem; 

<p>This function should return result of <b>TCalcItem</b>
type. If function returns string value, set <b>str</b> member of Result
variable and set <b>typ</b> member to <b>fdtstring</b> else set <b>data</b>
member and <b>typ</b> to <b>fdtnumber</b>. Use <b>setN</b> and <b>setS</b>
procedures to do it. 

<p>Function takes one parameter of <b>TFormulaCalc</b> type. <b>TFormulaCalc</b>
is stack object used to implement arithmetical and logical calculation. It has
many methods and properties but most useful are: 

<p><b>function</b> TopN: double; -
returns top value as number. 

<p><b>function</b> TopS: String; -
returns top value as string. 

<p><b>function</b>
ItemN(i:integer):double; - returns stack item value as number. ItemN(0) - top
element, Item(1) - next and so on. 

<p><b>function</b> ItemS(i:integer):string;
- returns stack item value as string. 

<p><b>function</b>
Item(i:integer):PCalcItem; - returns pointer to stack item. 

<p><b>property</b> Parent :
TArtFormula; - pointer to parent ArtFormula object. 

<p>You should understand, that parameters for function are
passed in stack. So last function parameter is the top (Item(0)) item in stack.
For example if function has three parameters first parameter will be ItemN(2)
or ItemS(2), second - ItemN(1) or ItemS(1), third - ItemN(0) or ItemS(0) (TopN
or TopS). 

<p>If you want to create variable argument list functions, you
should pass -1 as <b>paramcount</b> to <b>AddUserFunction</b>. For such
functions ArtFormula pass the number of parameters as last argument (top in
Calc stack). Variable argument list functions can take external variables evaluated
via <b>GetVarValue</b> and <b>GetVarsCount events</b> (if <b>ExternGetVar</b>
is true). Such external variables can return more then one value. It useful
e.g. for spreadsheet application when function parameter can be the range of
spreadsheet cells. Such external variables pass as one parameter in Calc stack
of <b>fdtgetvar</b> type. <b>StartGetVars</b> and <b>GetNextVar</b> methods
help you to deal with such parameters. Fist you should determine number of
arguments passed via stack (call TopN), then pass this value into <b>StartGetVars</b>
to begin evaluation of real parameters and then call <b>GetNextVar</b> until it
return false. See implementation of min, max, sum and other function to
understand this technique. 

<p>TArtFormula has special type of function called module.
Module can have its own functions. Module can be considered as functions
library or as object with methods and properties. 

<p>To create module, call <b>AddUserFunction</b> setting
module parameter to true. It creates main function of module. <b>AddUserFunction</b>
returns pointer to new allocated function table item which should be passed as
first argument of <b>AddModuleFunction</b> when you add function to the module.
The name of function passed to <b>AddUserFunction</b> becomes the name of the
module. You can call main function of module in ArtFormula program as usual
function. The call of other module function should be preceded by module name
and period (.). If you pass arguments to main function of module, ArtFormula
first calls main function. For example: <br>
<i>module('x').fun('y')</i> - calls main function with argument <i>'x'</i> and
then function <i>fun</i> with argument <i>'y'</i>; <br>
<i>module.fun('y')</i> - calls only function <i>fun</i> with argument <i>'y'</i>.


<p>The result of main function of module is passed as
additional (first) argument of other module function. This feature allows one
to use modules as objects. The common way to do so is to create internal table
of objects, write module function which creates new entry in table and returns
index. Main module function takes one parameter - index of object in internal
table and simply returns it. This index is passed as first parameter to other
module functions, so it is known with which object deal with. 

<p>For example: 

<p><i>$f := file.new; // creates new file object <br>
file($f).name := 'info'; <br>
file($f).open('read'); </i>

<p>ArtFunction module can't have data members but you can
easily create properties. To create property with name <i>SomeName</i> you
should write two functions. First one with name <i>SomeName</i> without
parameters to return property value and second one with name <i>SetSomeName</i>
with one parameter to set property value. So when ArtFormula meets statement <i>module.SomeName
:= Val</i> it automatically compiles it as <i>module.SetSomeName(Val)</i>. 

<p>See <i>File module</i> (af_file.pas in <i>demo</i> folder)
as example of module developing. 


<hr size=2 width="100%" align=center>


<p><b><font size=4 color='navy'>ArtFormula Syntax</font></b>

<p><b><font size=4>Preamble</font></b>

<p>ArtFormula has no statements in common meaning. All program
structure elements (branching, loops) are realized as function calls. So every
statement has parameters and result value. For example pascal block statement (<i>begin
... end</i>) is realized as <i>block(...)</i> function, if statement is call of
<i>condition()</i> function. TArtFormula component has predefined constant so
you can use pascal like notation instead of function calls. Also you can use
semicolon instead of comma. Below we will show both (function call and
statement like) syntax for all programming abilities of ArtFormula. 

<p><b><font size=4>Comments</font></b>

<p>Comments are ignored by TArtFormula compiler. There are two
ways to construct comments: text between a left brace and a right brace
constitutes a comment. Any text between a double-slash and the end of the line
constitutes a comment. 

<p><b><font size=4>Types end Expressions</font></b>

<p>ArtFormula has the only data type. Depending on expression
ArtFormula treats data value ether as numeric or string type. For comparison
operation (=, &lt;&gt; ,&gt;= , &lt;= , &gt;, &lt;) and addition ArtFormula
tries to convert operand first to numeric values and if this impossible to
string. For example: <i>&quot;123&quot; + 321</i> returns <i>444</i>, but <i>&quot;x123&quot;
+ 321</i> results in <i>&quot;x123321&quot;</i>. 

<p>Numeric literals (integer and real) can be represented in
common decimal notation. The dollar-sign prefix indicates a hexadecimal
numeral. The first hexadecimal digit after $ must be one of 0..9 - for example
$0AF (not $AF). 

<p>String value can be enclosed both in double and single
quotes. Two sequential apostrophes or double quotes in a same quoted string
denote a corresponded single character. To specify symbol with special ASCII
code use # symbol followed by corresponded integer constant. 

<p>There is no boolean type. As in C language ArtFormula
treats zero value as False and nonzero as True. 

<p>Date and time are represented as floating point value. 

<p><b><font size=4>Operators</font></b>

<p>Numeric operators: +, - , * , /, % (or <i>mod</i>), \ (or <i>div</i>),
^ (raise to a power). 

<p>Comparison operators: =, &lt;&gt;, &gt;, &lt;, &gt;=,
&lt;=. 

<p>Logical operators: &amp; (or <i>and</i>), | (or <i>or</i>),
<i>xor</i>, ! (or <i>not</i>). 

<p>Concatenation operator: @. 

<p>Difference in addition and concatenation operations is that
@ always treats its operands as strings, i.e. <i>&quot;123&quot; @ 321</i>
results in <i>&quot;123321&quot;</i> (unlike it <i>&quot;123&quot; + 321</i>
returns <i>444</i>). 

<p><b><font size=4>Constants</font></b>

<p>You can't define new constant in ArtFormula program. But
you can add constant by AddConstant procedure of TArtFormula component.
Constant in ArtFormula is not the same as in pascal. It more close to C
#define. If ArtFormula compiler meets constant, it replaces constant with
corresponded value. So you can define constant not only to specify numeric or
string values but also for token replacement. 

<p>For example you can define constant <i>MyIf</i> equals to <i>If
x=0 then return(0) endif</i> and use <i>MyIf</i> as new statement. 

<p><b><font size=4>Predefined functions</font></b> 

<p>As ArtFormula descended from simple expression evaluation
class, it has a wide number of predefined functions. 

<p><b><i>Numeric functions:</i></b> 

<p>Trigonometric, hyperbolic and invert functions: <br>
<i>sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), cosh(x), sinh(x),
tanh(x), asinh(x), acosh(x), atanh(x)</i> <br>
Exponential and logarithmical functions: <br>
<i>log(x), lg(x) (log base 10), exp(x), sqrt(x)</i> <br>
Integer and factional part of number: <i>int, frac</i> <br>
Absolute value: <i>abs</i> <br>
Sign of a number: <i>sign</i> <br>
Random value and initialization of the random number generator: <i>rnd(x),
randomize</i> 

<p><b><i>Statistical functions (all statistical functions take
variable argument list):</i></b> 

<p><i>max(x1,x2,...)</i> - maximum of
passed values, <br>
<i>min(x1,x2,...)</i> - minimum of passed values, <br>
<i>avg(x1,x2,...)</i> - average value, <br>
<i>stddev(x1,x2,...)</i> - standard deviation (unbiased), <br>
<i>stddevp(x1,x2,...)</i> - standard deviation (biased), <br>
<i>sum(x1,x2,...)</i> - sum of passed values, <br>
<i>sumofsquares(x1,x2,