Difference between revisions of "How To Use TFPExpressionParser"

From Lazarus wiki
(Built-in categories)
(Use <syntaxhighlight> only in code paragraphs.)
 
(9 intermediate revisions by the same user not shown)
Line 4: Line 4:
  
  
TFPExpressionParser allows to analyze and calculate [[expression|expressions]] such as <syntaxhighlight lang="pascal" enclose="none">sin(x)*cos(2*x)</syntaxhighlight> for any value of the [[Variable|variable]] <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight>. Besides mathematical expressions it can also handle [[Boolean|boolean]], string formulas, [[TDateTime|date/time]] values etc. Even user-provided functions can be linked in.  
+
<tt>TFPExpressionParser</tt> allows to analyze and calculate [[expression|expressions]] such as <tt>sin(x)*cos(2*x)</tt> for any value of the [[Variable|variable]] <tt>x</tt>. Besides mathematical expressions it can also handle [[Boolean|boolean]] values, string formulas, [[TDateTime|date/time]] values etc. Even user-provided functions can be linked in.  
  
It belongs to [[FPC]] [[FCL|Free Component Library (FCL)]] and is implemented in the [[Unit|unit]] <syntaxhighlight lang="pascal" enclose="none">fpexprpars.pp</syntaxhighlight>, folder <syntaxhighlight lang="pascal" enclose="none">(fpc_source_dir)/packages/fcl-base/src</syntaxhighlight>. Just add <syntaxhighlight lang="pascal" enclose="none">fpexprpars</syntaxhighlight> to the [[Uses|uses]] clauses to get access to its functionality. See the file "fpexprpars.txt" (in <syntaxhighlight lang="pascal" enclose="none">(fpc_source_dir)/packages/fcl-base/examples</syntaxhighlight>) for a short documenation.
+
It belongs to [[FPC]] [[FCL|Free Component Library (FCL)]] and is implemented in the [[Unit|unit]] <tt>fpexprpars.pp</tt>, folder <tt>(fpc_source_dir)/packages/fcl-base/src</tt>. Just add <tt>fpexprpars</tt> to the [[Uses|uses]] clauses to get access to its functionality. See the file "fpexprpars.txt" (in <tt>(fpc_source_dir)/packages/fcl-base/examples</tt>) for a short documenation.
  
 
== Creating the parser ==
 
== Creating the parser ==
Line 21: Line 21:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
If this is called from a [[Method|method]] of a [[TForm|form]], "[[Self|self]]" points to the form. Since the parser inherits from <syntaxhighlight lang="pascal" enclose="none">TComponent</syntaxhighlight>, there is no need to destroy it explicitly since its owner, the form, will do it. On the other hand, it is also possible to create the parser from anywhere in a [[Program|program]] without a form or even [[Class|class]] being involved; in this case use <code>[[Nil|nil]]</code> as the owner of the parser, but don't forget to <syntaxhighlight lang="pascal" enclose="none">.Free</syntaxhighlight> the parser after its usage:
+
If this is called from a [[Method|method]] of a [[TForm|form]], "[[Self|self]]" points to the form. Since the parser inherits from <tt>TComponent</tt>, there is no need to destroy it explicitly since its owner, the form, will do it. On the other hand, it is also possible to create the parser from anywhere in a [[Program|program]] without a form or even [[Class|class]] being involved; in this case use <tt>[[Nil|nil]]</tt> as the owner of the parser, but don't forget to <tt>.Free</tt> the parser after its usage:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 40: Line 40:
  
 
== Built-in categories ==
 
== Built-in categories ==
The parser is designed in a very flexible way, but the default parser is quite dumb. You have to specify which kind of expressions it will accept. This is done by adding the corresponding [[Identifier|identifier]] to the set of built-in categories. They are accessible by the parser's [[Property|property]] <syntaxhighlight lang="pascal" enclose="none">BuiltIns</syntaxhighlight>:
+
The parser is designed in a very flexible way, but the default parser is quite dumb. You have to specify which kind of expressions it will accept. This is done by adding the corresponding [[Identifier|identifier]] to the set of built-in categories. They are accessible by the parser's [[Property|property]] <tt>BuiltIns</tt>:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 48: Line 48:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Here is a collection of the built-in symbols which can be used by adding categories to the parser's <syntaxhighlight lang="pascal" enclose="none">BuiltIns</syntaxhighlight> - it should be clear to anybody who "speaks" [[Pascal]] what these symbols mean...
+
Here is a collection of the built-in symbols which can be used by adding categories to the parser's <tt>BuiltIns</tt> - it should be clear to anybody who "speaks" [[Pascal]] what these symbols mean...
* '''bcStrings''': <syntaxhighlight lang="pascal" enclose="none">Length</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Copy</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Delete</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Pos</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Lowercase</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Uppercase</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StringReplace</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">CompareText</syntaxhighlight>
+
* '''bcStrings''': <tt>Length</tt>, <tt>Copy</tt>, <tt>Delete</tt>, <tt>Pos</tt>, <tt>Lowercase</tt>, <tt>Uppercase</tt>, <tt>StringReplace</tt>, <tt>CompareText</tt>
* '''bcDateTime''': <syntaxhighlight lang="pascal" enclose="none">Date</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Time</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Now</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">DayOfWeek</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractYear</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractMonth</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractDay</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractHour</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractMin</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ExtractSec</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">Extractmsec</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">EncodeDate</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">EncodeTime</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ShortDayName</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ShortMonthName</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">LongDayName</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">LongMonthName</syntaxhighlight>
+
* '''bcDateTime''': <tt>Date</tt>, <tt>Time</tt>, <tt>Now</tt>, <tt>DayOfWeek</tt>, <tt>ExtractYear</tt>, <tt>ExtractMonth</tt>, <tt>ExtractDay</tt>, <tt>ExtractHour</tt>, <tt>ExtractMin</tt>, <tt>ExtractSec</tt>, <tt>Extractmsec</tt>, <tt>EncodeDate</tt>, <tt>EncodeTime</tt>, <tt>ShortDayName</tt>, <tt>ShortMonthName</tt>, <tt>LongDayName</tt>, <tt>LongMonthName</tt>
* '''bcMath''': <syntaxhighlight lang="pascal" enclose="none">cos</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">sin</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">arctan</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">abs</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">sqr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">sqrt</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">exp</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">ln</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">log</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">frac</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">int</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">round</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">trunc</syntaxhighlight>,
+
* '''bcMath''': <tt>cos</tt>, <tt>sin</tt>, <tt>arctan</tt>, <tt>abs</tt>, <tt>sqr</tt>, <tt>sqrt</tt>, <tt>exp</tt>, <tt>ln</tt>, <tt>log</tt>, <tt>frac</tt>, <tt>int</tt>, <tt>round</tt>, <tt>trunc</tt>,
* '''bcBoolean''': <syntaxhighlight lang="pascal" enclose="none">shl</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">shr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">IFS</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">IFF</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">IFD</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">IFI</syntaxhighlight> (The <syntaxhighlight lang="pascal" enclose="none">IFxxx</syntaxhighlight> symbols have the same effect as fpc's <syntaxhighlight lang="pascal" enclose="none">IfThen</syntaxhighlight> for string (<syntaxhighlight lang="pascal" enclose="none">IFS</syntaxhighlight>), floating point (<syntaxhighlight lang="pascal" enclose="none">IFF</syntaxhighlight>), date/time (<syntaxhighlight lang="pascal" enclose="none">IFD</syntaxhighlight>), or integer (<syntaxhighlight lang="pascal" enclose="none">IFI</syntaxhighlight>) variables)
+
* '''bcBoolean''': <tt>shl</tt>, <tt>shr</tt>, <tt>IFS</tt>, <tt>IFF</tt>, <tt>IFD</tt>, <tt>IFI</tt> (The <tt>IFxxx</tt> symbols have the same effect as fpc's <tt>IfThen</tt> for string (<tt>IFS</tt>), floating point (<tt>IFF</tt>), date/time (<tt>IFD</tt>), or integer (<tt>IFI</tt>) variables)
* '''bcConversion''': <syntaxhighlight lang="pascal" enclose="none">IntToStr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToInt</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToIntDef</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">FloatToStr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToFloat</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToFloatDef</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">BoolToStr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToBool</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToBoolDef</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">DateToStr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">TimeToStr</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToDate</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToDateDef</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToTime</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToTimeDef</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToDateTime</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">StrToDateTimeDef</syntaxhighlight>
+
* '''bcConversion''': <tt>IntToStr</tt>, <tt>StrToInt</tt>, <tt>StrToIntDef</tt>, <tt>FloatToStr</tt>, <tt>StrToFloat</tt>, <tt>StrToFloatDef</tt>, <tt>BoolToStr</tt>, <tt>StrToBool</tt>, <tt>StrToBoolDef</tt>, <tt>DateToStr</tt>, <tt>TimeToStr</tt>, <tt>StrToDate</tt>, <tt>StrToDateDef</tt>, <tt>StrToTime</tt>, <tt>StrToTimeDef</tt>, <tt>StrToDateTime</tt>, <tt>StrToDateTimeDef</tt>
* '''bcAggregate''': <syntaxhighlight lang="pascal" enclose="none">count</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">sum</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">avg</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">min</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">max</syntaxhighlight>
+
* '''bcAggregate''': <tt>count</tt>, <tt>sum</tt>, <tt>avg</tt>, <tt>min</tt>, <tt>max</tt>
  
<syntaxhighlight lang="pascal" enclose="none">bcData</syntaxhighlight>, <syntaxhighlight lang="pascal" enclose="none">bcVaria</syntaxhighlight>, and <syntaxhighlight lang="pascal" enclose="none">bcUser</syntaxhighlight> are not used anywhere within fpexprpars. The [[#Adding user-defined functions|last section]] gives instructions how to extend the parser with more functions.
+
<tt>bcData</tt>, <tt>bcVaria</tt>, and <tt>bcUser</tt> are not used anywhere within <tt>fpexprpars</tt>. The [[#Adding user-defined functions|last section]] gives instructions how to extend the parser with more functions.
  
 
{{Note|These symbols are not [[case-sensitive]].}}
 
{{Note|These symbols are not [[case-sensitive]].}}
  
In order to use a mathematical expression the option <syntaxhighlight lang="pascal" enclose="none">bcMath</syntaxhighlight> has to be added to the parser's <syntaxhighlight lang="pascal" enclose="none">Builtins</syntaxhighlight>:
+
In order to use a mathematical expression the option <tt>bcMath</tt> has to be added to the parser's <tt>Builtins</tt>:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 68: Line 68:
 
== Expressions ==
 
== Expressions ==
 
=== An expression with constants ===
 
=== An expression with constants ===
As a first example we have the parser calculate a very simple expression <syntaxhighlight lang="pascal" enclose="none">1+1</syntaxhighlight>.
+
As a first example we have the parser calculate a very simple expression <tt>'1+1'</tt>.
  
The first step is to tell the parser which expression is to be calculated. There is a property <syntaxhighlight lang="pascal" enclose="none">Expression</syntaxhighlight> for this purpose:
+
The first step is to tell the parser which expression is to be calculated. There is a property <tt>Expression</tt> for this purpose:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 76: Line 76:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The next step is to calculate the expression: just call <syntaxhighlight lang="pascal" enclose="none">Evaluate</syntaxhighlight> or <syntaxhighlight lang="pascal" enclose="none">EvaluateExpression</syntaxhighlight> - the former is is a [[Function|function]] while the latter one is a [[Procedure|procedure]] which passes the result as a parameter.  
+
The next step is to calculate the expression: just call <tt>Evaluate</tt> or <tt>EvaluateExpression</tt> - the former is is a [[Function|function]] while the latter one is a [[Procedure|procedure]] which passes the result as a parameter.  
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 86: Line 86:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
What is that mysterious <syntaxhighlight lang="pascal" enclose="none">TFPExpressionResult</syntaxhighlight>? Since the parser is very flexible and can deal with numbers, strings, date/times or booleans there must be a more complex data type which returns a calculation result:
+
What is that mysterious <tt>TFPExpressionResult</tt>? Since the parser is very flexible and can deal with numbers, strings, date/times or booleans there must be a more complex data type which returns a calculation result:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 103: Line 103:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The member <syntaxhighlight lang="pascal" enclose="none">ResultType</syntaxhighlight> signals which one of the data fields is valid. It is important to understand this since the expression parser is very strict on [[Data type|data types]].
+
The member <tt>ResultType</tt> signals which one of the data fields is valid. It is important to understand this since the expression parser is very strict on [[Data type|data types]].
  
In our example, we are adding two [[Integer|integers]], therefore the result is an integer as well. If, on the other had, we had used the expression <syntaxhighlight lang="pascal" enclose="none">"1.0 + 1"</syntaxhighlight>, the first number would have been a floating point value, and the result would have been a float! Therefore, always have a look at the member <syntaxhighlight lang="pascal" enclose="none">ResultType</syntaxhighlight> of the <syntaxhighlight lang="pascal" enclose="none">TFPExpressionResult</syntaxhighlight> before picking the result. To simplify the usage of the expression result data type, <syntaxhighlight lang="pascal" enclose="none">fpexprpars</syntaxhighlight> exposes a function <syntaxhighlight lang="pascal" enclose="none">ArgToFloat</syntaxhighlight> which gets the entire expression result [[Record|record]] as a parameter and selects the right component if a floating point result is expected:
+
In our example, we are adding two [[Integer|integers]], therefore the result is an integer as well. If, on the other had, we had used the expression <tt>'1.0 + 1'</tt>, the first number would have been a floating point value, and the result would have been a float! Therefore, always have a look at the member <tt>ResultType</tt> of the <tt>TFPExpressionResult</tt> before picking the result. To simplify the usage of the expression result data type, <tt>fpexprpars</tt> exposes a function <tt>ArgToFloat</tt> which gets the entire expression result [[Record|record]] as a parameter and selects the right component if a floating point result is expected:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 116: Line 116:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{Note|Floating point constants in expressions must have a [[period|point]] as decimal separator, not a [[Comma|comma]] as used in some European countries. If your expression string comes from user input and contains decimal commas you have to replace the commas by points first before assigning it to the parsers's <syntaxhighlight lang="pascal" enclose="none">Expression</syntaxhighlight>. }}
+
{{Note|Floating point constants in expressions must have a [[period|point]] as decimal separator, not a [[Comma|comma]] as used in some European countries. If your expression string comes from user input and contains decimal commas you have to replace the commas by points first before assigning it to the parsers's <tt>Expression</tt>. }}
  
 
=== An expression with a variable ===
 
=== An expression with a variable ===
In this example, we calculate the value of <syntaxhighlight lang="pascal" enclose="none">sin(x)*cos(2*x)</syntaxhighlight> for <syntaxhighlight lang="pascal" enclose="none">x = 0.5</syntaxhighlight>.
+
In this example, we calculate the value of <tt>sin(x)*cos(2*x)</tt> for <tt>x = 0.5</tt>.
  
 
==== Defining variables ====
 
==== Defining variables ====
At first we have to define the variables. We have only one, <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight>. The parser has a [[Method|method]] <syntaxhighlight lang="pascal" enclose="none">AddFloatVariable</syntaxhighlight> to declare a floating point variable; there are also methods
+
At first we have to define the variables. We have only one, <tt>x</tt>. The parser has a [[Method|method]] <tt>AddFloatVariable</tt> to declare a floating point variable; there are also methods
 
   
 
   
* <syntaxhighlight lang="pascal" enclose="none">AddBooleanVariable</syntaxhighlight>
+
* <tt>AddBooleanVariable</tt>
* <syntaxhighlight lang="pascal" enclose="none">AddStringVariable</syntaxhighlight>
+
* <tt>AddStringVariable</tt>
* <syntaxhighlight lang="pascal" enclose="none">AddDateTimeVariable</syntaxhighlight>
+
* <tt>AddDateTimeVariable</tt>
  
 
for boolean, string and date/time variables, respectively.
 
for boolean, string and date/time variables, respectively.
  
Each one of these methods expects the name of the variable along with its default value. For the sample function <syntaxhighlight lang="pascal" enclose="none">sin(x)*cos(2*x)</syntaxhighlight> we just call:
+
Each one of these methods expects the name of the variable along with its default value. For our sample function we just call:
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
 
   FParser.Identifiers.AddFloatVariable('x', 0.5);
 
   FParser.Identifiers.AddFloatVariable('x', 0.5);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
<syntaxhighlight lang="pascal" enclose="none">0.5</syntaxhighlight> is entered here as a default value because that is the argument at which we want to calculate the expression (it will be shown [[#Changing_variables|below]] how to modify a variable). From now on, the parser will use this number whenever it finds the variable <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight> in the expression.
+
<tt>0.5</tt> is entered here as a default value because that is the argument at which we want to calculate the expression (it will be shown [[#Changing_variables|below]] how to modify a variable). From now on, the parser will use this number whenever it finds the variable <tt>x</tt> in the expression.
  
Of course, you can add other names, e.g. [[Constant|constants]] like <syntaxhighlight lang="pascal" enclose="none">e</syntaxhighlight>, etc. (The number [[Pi|<syntaxhighlight lang="pascal" enclose="none">pi</syntaxhighlight>]] is already built-in).
+
Of course, you can add other names, e.g. [[Constant|constants]] like <tt>e</tt>, etc. (The number [[Pi|<tt>pi</tt>]] is already built-in).
  
 
==== Defining the expression ====
 
==== Defining the expression ====
Line 170: Line 170:
  
 
==== Changing variables ====
 
==== Changing variables ====
So far, <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight> always has the value 0.5 - it behaves like a constant, we could have used the expression <syntaxhighlight lang="pascal" enclose="none">"sin(0.5)*cos(2*0.5)"</syntaxhighlight> as well.
+
So far, <tt>x</tt> always has the value 0.5 - it behaves like a constant, we could have used the expression <tt>'sin(0.5)*cos(2*0.5)'</tt> as well.
  
To make it behave more like a "variable", we now calculate the test function for the <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight> values between -10 and 10 at integer steps.
+
To make it behave more like a "variable", we now calculate the test function for the <tt>x</tt> values between <tt>-10</tt> and <tt>10</tt> at integer steps.
  
The main question is: How to replace the value assigned to a variable? There are several possibilities - all of them require the internal variable <syntaxhighlight lang="pascal" enclose="none">Identifier</syntaxhighlight> (type <syntaxhighlight lang="pascal" enclose="none">TFPExprIdentifierDef</syntaxhighlight>) which exposes various ways to access variables and their properties:
+
The main question is: How to replace the value assigned to a variable? There are several possibilities - all of them require the internal variable <tt>Identifier</tt> (type <tt>TFPExprIdentifierDef</tt>) which exposes various ways to access variables and their properties:
* Use the return value of the <syntaxhighlight lang="pascal" enclose="none">AddFloatVariable</syntaxhighlight> function.
+
* Use the return value of the <tt>AddFloatVariable</tt> function.
* Seek an identifier by calling <syntaxhighlight lang="pascal" enclose="none">FindIdentifierByName</syntaxhighlight> with the variable name as a parameter.
+
* Seek an identifier by calling <tt>FindIdentifierByName</tt> with the variable name as a parameter.
* Access the identifier from the <syntaxhighlight lang="pascal" enclose="none">Identifiers</syntaxhighlight> collection of the parser by using the known index of the variable: We had added <syntaxhighlight lang="pascal" enclose="none">x</syntaxhighlight> as the only variable, therefore, it must be at index 0.
+
* Access the identifier from the <tt>Identifiers</tt> collection of the parser by using the known index of the variable: We had added <tt>x</tt> as the only variable, therefore, it must be at index 0.
  
Once the <syntaxhighlight lang="pascal" enclose="none">Identifier</syntaxhighlight> is known, the value of the variable can be changed by accessing the property <syntaxhighlight lang="pascal" enclose="none">AsFloat</syntaxhighlight> (or <syntaxhighlight lang="pascal" enclose="none">AsDateTime</syntaxhighlight> etc. accordingly):
+
Once the <tt>Identifier</tt> is known, the value of the variable can be changed by accessing the property <tt>AsFloat</tt> (or <tt>AsDateTime</tt> etc. accordingly):
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 217: Line 217:
 
end;  
 
end;  
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
=== Operators ===
 +
The expressions discussed above show that standard operators <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt>, <tt>&lt;</tt>, <tt>&lt;=</tt>, etc., can be used to setup an expression. Additionally, in recent FPC versions, the operator <tt>^</tt> is available for calculating the power, and <tt>mod</tt> for the remainder of integer divisions (modulo).
  
 
=== Aggregate functions ===
 
=== Aggregate functions ===
 
In addition to "normal" function the parser supports also "aggregate" functions which are repeatedly applied to a variable, e.g. <tt>sum(x)</tt> which adds up all the values assigned to the variable <tt>x</tt>. These functions are available:
 
In addition to "normal" function the parser supports also "aggregate" functions which are repeatedly applied to a variable, e.g. <tt>sum(x)</tt> which adds up all the values assigned to the variable <tt>x</tt>. These functions are available:
* <tt>min(x)</tt> - Calculate the minimum of all values assigned to x
+
* <tt>min(x)</tt> - Calculate the minimum of all values assigned to <tt>x</tt>
* <tt>max(x)</tt> - Calculate the maximum of all values assigned to x
+
* <tt>max(x)</tt> - Calculate the maximum of all values assigned to <tt>x</tt>
* <tt>sum(x)</tt> - Calculate the sum of all values assigned to x
+
* <tt>sum(x)</tt> - Calculate the sum of all values assigned to <tt>x</tt>
* <tt>avg(x)</tt> - Calculate the average of the values assigned to x
+
* <tt>avg(x)</tt> - Calculate the average of the values assigned to <tt>x</tt>
* <tt>count(x)</tt> - Count the numbers assigned to x
+
* <tt>count(x)</tt> - Count the numbers assigned to <tt>x</tt>
  
In order to have aggregate functions available the category <code>bcAggregate</code> must be added to the <code>BuiltIns</code> of the parser. Next step is to define a variable to which the aggregate function will be applied. The aggregation process must be initialized by calling the parser method <code>InitAggregate</code>; and whenever the variable value is changed the method <code>UpdateAggregate</code> must be alled.
+
In order to have aggregate functions available the category <tt>bcAggregate</tt> must be added to the <tt>BuiltIns</tt> of the parser. Next step is to define a variable to which the aggregate function will be applied. The aggregation process must be initialized by calling the parser method <tt>InitAggregate</tt>; and whenever the variable value is changed the method <tt>UpdateAggregate</tt> must be called.
  
 
Here is an example which calculates the sum of the elements of an array:
 
Here is an example which calculates the sum of the elements of an array:
Line 235: Line 238:
 
   Data: array[0..5] of Double = (1.221, 3.4, -1.0, -0.221, -3.0, -0.4);
 
   Data: array[0..5] of Double = (1.221, 3.4, -1.0, -0.221, -3.0, -0.4);
 
var
 
var
   parser: TFPExpressionParser;
+
   FParser: TFPExpressionParser;
 
   xVar: TFPExprIdentifierDef;
 
   xVar: TFPExprIdentifierDef;
 
   x: Double;
 
   x: Double;
 
begin
 
begin
   parser := TFPExpressionParser.Create(nil);
+
   FParser := TFPExpressionParser.Create(nil);
 
   try
 
   try
     parser.BuiltIns := [bcAggregate];
+
     FParser.BuiltIns := [bcAggregate];
     xVar := parser.Identifiers.AddFloatVariable('x', 0);
+
     xVar := FParser.Identifiers.AddFloatVariable('x', 0);
     parser.Expression := 'sum(x)';
+
     FParser.Expression := 'sum(x)';
     parser.InitAggregate;
+
     FParser.InitAggregate;
 
     WriteLn('Sum of');
 
     WriteLn('Sum of');
 
     for x in Data do
 
     for x in Data do
Line 250: Line 253:
 
       xVar.AsFloat := x;
 
       xVar.AsFloat := x;
 
       WriteLn(xVar.AsFloat:10:3);
 
       WriteLn(xVar.AsFloat:10:3);
       parser.UpdateAggregate;
+
       FParser.UpdateAggregate;
 
     end;
 
     end;
 
     WriteLn('----------');
 
     WriteLn('----------');
     WriteLn(parser.Evaluate.ResFloat:10:3);
+
     WriteLn(FParser.Evaluate.ResFloat:10:3);
 
   finally
 
   finally
     parser.Free;
+
     FParser.Free;
 
   end;
 
   end;
  
Line 262: Line 265:
  
 
== Adding user-defined functions ==
 
== Adding user-defined functions ==
The default parser only knows the built-in functions mentioned above. One of the strengths of of the expression parser is that it is very easy to extend to include other functions. This can be done by calling the method <syntaxhighlight lang="pascal" enclose="none">Identifiers.AddFunction</syntaxhighlight>, e.g.
+
The default parser only knows the built-in functions mentioned above. One of the strengths of of the expression parser is that it is very easy to extend to include other functions. This can be done by calling the method <tt>Identifiers.AddFunction</tt>, e.g.
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
 
   FParser.Identifiers.AddFunction('tan', 'F', 'F', @ExprTan);
 
   FParser.Identifiers.AddFunction('tan', 'F', 'F', @ExprTan);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
In this example, we add the function tan(x) by specifying its name as it will be called in the function expressions (first parameter), the type of the result values (second parameter, "F" = float, "I" = integer, "D" = date/time, "S" = string, or "B" = boolean) and the type of the input values (third parameter, same logic). If a function accepts several input parameters the type of each one must be specified, e.g. by 'FF' for two floating point values, or 'FI' for a first float and a second integer parameter. The last parameter points to the function which is called whenever "tan" is found in the expression string. Since this function has a particular syntax we have to implement it in our own source code:
+
In this example, we add the function <tt>tan(x)</tt> by specifying its name as it will be called in the function expressions (first parameter), the type of the result values (second parameter, "F" = float, "I" = integer, "D" = date/time, "S" = string, or "B" = boolean) and the type of the input values (third parameter, same logic). If a function accepts several input parameters the type of each one must be specified, e.g. by 'FF' for two floating point values, or 'FI' for a first float and a second integer parameter. The last parameter points to the function which is called whenever "tan" is found in the expression string. Since this function has a particular syntax we have to implement it in our own source code:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
procedure ExprTan(var Result: TFPExpressionResult; Const Args: TExprParameterArray);
+
procedure ExprTan(var Res: TFPExpressionResult; Const Args: TExprParameterArray);
 
var
 
var
 
   x: Double;
 
   x: Double;
 
begin
 
begin
 
   x := ArgToFloat(Args[0]);
 
   x := ArgToFloat(Args[0]);
   Result.resFloat := tan(x);
+
   Res.resFloat := tan(x);
 +
end;
 +
</syntaxhighlight>
 +
 
 +
The result of the calculation is returned as parameter <tt>Res</tt> which is of the <tt>TFPExpressionResult</tt> type that we met above. The arguments for the calculation are passed by <tt>Args</tt> which is just an array of <tt>TFPExpressionResult</tt> values - again because parameters can have several data types. The word <tt>''Result''</tt> in <tt>TFPExpressionResult</tt> is maybe a bit misleading here, because this array holds all the *input* parameters as specified by the input types of the <tt>AddFunction</tt> method.
 +
 
 +
When, in fpc 3.2 or later, the input parameter symbol string of the <tt>AddFunction</tt> method ends with a <tt>'+'</tt> then parameters with the previous type can be repeated as often as needed; this way a function with a variable parameter count can be implemented. In the following example, we add the function <tt>SumOf</tt> which adds up as many values as provided:
 +
 
 +
<syntaxhighlight lang="Pascal">
 +
procedure ExprSumOf(var Res: TFPExpressionResult; Const Args: TExprParameterArray);
 +
var
 +
  sum: Double;
 +
  arg: TFPExpressionResult;
 +
begin
 +
  sum := 0;
 +
  for arg in Args do
 +
    sum := sum + ArgToFloat(arg);
 +
  Res.ResFloat := sum;
 
end;
 
end;
 +
 +
begin
 +
  ...
 +
  FParser.Identifiers.AddFunction('SumOf', 'F', 'F+', @ExprSumOf);
 +
  FParser.Expression := 'SumOf(-1,2,3,4.1)';  // arbitrary number of arguments!
 +
  WriteLn(FParser.Evaluate.ResFloat:0:3);
 +
  ...
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The result of the calculation is returned as parameter <syntaxhighlight lang="pascal" enclose="none">"Result"</syntaxhighlight> which is a <syntaxhighlight lang="pascal" enclose="none">TFPExpressionResult</syntaxhighlight> that we met above. The arguments for the calculation are passed by <syntaxhighlight lang="pascal" enclose="none">Args</syntaxhighlight> which is just an array of TFPExpressionResult values - again because parameters can have several data types. The term TFPExpression''Results'' is maybe a bit misleading here, because this array holds all the *input* parameters as specified by the input types of the AddFunction method.
+
== Some special code ==
 +
=== Can I change the built-in function <tt>sin(x)</tt> to accept arguments in degrees, instead of radians? ===
 +
Yes. All built-in functions are collected in the instance <tt>BuiltInIdentifiers</tt> of class <tt>TExprBuiltInManager</tt>. Find the built-in identifier (<tt>BuiltInIdentifiers.Find('sin')</tt>, delete it and replace it by a user-defined function having the requested behavior. In FPC 3.2 or later, the identifier can be removed directly (<tt>BuiltInIdentifiers.Remove('sin')</tt>), in order versions the <tt>BuiltInIdentifiers</tt> must be cast to a descendant of <tt>TExprBuiltInManager</tt> in order to access the <tt>Delete</tt> method of its protected collection <tt>Defs</tt>:
 +
<syntaxhighlight lang="pascal">
 +
uses
 +
  Math, fpExprPars;
 +
 +
// these are needed only for fpc before v3.2
 +
{
 +
type
 +
  TMyBuiltinManager = class(TExprBuiltinManager);
 +
var
 +
  idx: Integer;
 +
}
 +
 +
var
 +
  parser: TFPExpressionParser;
 +
 +
  Procedure ExprSin(Var Result: TFPExpressionResult; Const Args: TExprParameterArray);
 +
  begin
 +
    Result.resFloat := Sin(DegToRad(ArgToFloat(Args[0])));  // convert radians to degrees
 +
  end;
 +
 +
begin
 +
  // fpc 3.2+
 +
  BuiltInIdentifiers.Remove('sin');
 +
  // or in older versions:
 +
{ idx := BuiltinIdentifiers.IndexOfIdentifier('sin');
 +
  TMyBuiltinManager(BuiltinIdentifiers).Defs.Delete(idx);
 +
}
 +
  BuiltinIdentifiers.AddFunction(bcMath, 'sin', 'F', 'F', @ExprSin);
 +
 +
  parser := TFPExpressionParser.Create(nil);
 +
  try
 +
    parser.BuiltIns := [bcMath];
 +
    parser.Expression := 'sin(45.0)';
 +
    WriteLn(parser.Evaluate.ResFloat:0:5);
 +
    parser.Expression := 'sin(90.0)';
 +
    WriteLn(parser.Evaluate.ResFloat:0:5);
 +
    parser.Expression := 'sin(180.0)';
 +
    WriteLn(parser.Evaluate.ResFloat:0:5);
 +
  finally
 +
    parser.Free;
 +
  end;
 +
             
 +
  WriteLn('Press ENTER to close.');
 +
  ReadLn;
 +
end. </syntaxhighlight>

Latest revision as of 22:01, 8 October 2021


English (en) suomi (fi)


TFPExpressionParser allows to analyze and calculate expressions such as sin(x)*cos(2*x) for any value of the variable x. Besides mathematical expressions it can also handle boolean values, string formulas, date/time values etc. Even user-provided functions can be linked in.

It belongs to FPC Free Component Library (FCL) and is implemented in the unit fpexprpars.pp, folder (fpc_source_dir)/packages/fcl-base/src. Just add fpexprpars to the uses clauses to get access to its functionality. See the file "fpexprpars.txt" (in (fpc_source_dir)/packages/fcl-base/examples) for a short documenation.

Creating the parser

You apply the parser by creating an instance like this:

uses
  fpexprpars;

var
  FParser: TFPExpressionParser;
begin
  FParser := TFpExpressionParser.Create(self);
  // ... do something (see below)

If this is called from a method of a form, "self" points to the form. Since the parser inherits from TComponent, there is no need to destroy it explicitly since its owner, the form, will do it. On the other hand, it is also possible to create the parser from anywhere in a program without a form or even class being involved; in this case use nil as the owner of the parser, but don't forget to .Free the parser after its usage:

uses
  fpexprpars;

var
  FParser: TFPExpressionParser;
begin
  FParser := TFPExpressionParser.Create(nil);
  try
    // ... do something (see below)
  finally
    FParser.Free;
  end;
end;

Built-in categories

The parser is designed in a very flexible way, but the default parser is quite dumb. You have to specify which kind of expressions it will accept. This is done by adding the corresponding identifier to the set of built-in categories. They are accessible by the parser's property BuiltIns:

type
  TBuiltInCategory = (bcStrings, bcDateTime, bcMath, bcBoolean, bcConversion, bcData, bcVaria, bcUser, bcAggregate);
  TBuiltInCategories = set of TBuiltInCategory;

Here is a collection of the built-in symbols which can be used by adding categories to the parser's BuiltIns - it should be clear to anybody who "speaks" Pascal what these symbols mean...

  • bcStrings: Length, Copy, Delete, Pos, Lowercase, Uppercase, StringReplace, CompareText
  • bcDateTime: Date, Time, Now, DayOfWeek, ExtractYear, ExtractMonth, ExtractDay, ExtractHour, ExtractMin, ExtractSec, Extractmsec, EncodeDate, EncodeTime, ShortDayName, ShortMonthName, LongDayName, LongMonthName
  • bcMath: cos, sin, arctan, abs, sqr, sqrt, exp, ln, log, frac, int, round, trunc,
  • bcBoolean: shl, shr, IFS, IFF, IFD, IFI (The IFxxx symbols have the same effect as fpc's IfThen for string (IFS), floating point (IFF), date/time (IFD), or integer (IFI) variables)
  • bcConversion: IntToStr, StrToInt, StrToIntDef, FloatToStr, StrToFloat, StrToFloatDef, BoolToStr, StrToBool, StrToBoolDef, DateToStr, TimeToStr, StrToDate, StrToDateDef, StrToTime, StrToTimeDef, StrToDateTime, StrToDateTimeDef
  • bcAggregate: count, sum, avg, min, max

bcData, bcVaria, and bcUser are not used anywhere within fpexprpars. The last section gives instructions how to extend the parser with more functions.

Note-icon.png

Note: These symbols are not case-sensitive.

In order to use a mathematical expression the option bcMath has to be added to the parser's Builtins:

  FParser.Builtins := [bcMath];   // or FParser.Builtins := FParser.Builtins + [bcMath];

Expressions

An expression with constants

As a first example we have the parser calculate a very simple expression '1+1'.

The first step is to tell the parser which expression is to be calculated. There is a property Expression for this purpose:

  FParser.Expression := '1+1';

The next step is to calculate the expression: just call Evaluate or EvaluateExpression - the former is is a function while the latter one is a procedure which passes the result as a parameter.

var
  parserResult: TFPExpressionResult;
begin
 ....
  parserResult := FParser.Evaluate;  // or: FParser.EvaluateExpression(parserResult);

What is that mysterious TFPExpressionResult? Since the parser is very flexible and can deal with numbers, strings, date/times or booleans there must be a more complex data type which returns a calculation result:

type
  TResultType = (rtBoolean, rtInteger, rtFloat, tDateTime, rtString);

  TFPExpressionResult = record
    ResString   : String;
    Case ResultType : TResultType of
      rtBoolean  : (ResBoolean  : Boolean);
      rtInteger  : (ResInteger  : Int64);
      rtFloat    : (ResFloat    : TExprFloat);
      rtDateTime : (ResDateTime : TDatetime);
      rtString   : ();
  end;

The member ResultType signals which one of the data fields is valid. It is important to understand this since the expression parser is very strict on data types.

In our example, we are adding two integers, therefore the result is an integer as well. If, on the other had, we had used the expression '1.0 + 1', the first number would have been a floating point value, and the result would have been a float! Therefore, always have a look at the member ResultType of the TFPExpressionResult before picking the result. To simplify the usage of the expression result data type, fpexprpars exposes a function ArgToFloat which gets the entire expression result record as a parameter and selects the right component if a floating point result is expected:

var
  parserResult: TFPExpressionResult;
  resultValue: Double;
...
  parserResult := FParser.Evaluate;   // or: FParser.EvaluateExpression(parserResult);
  resultValue := ArgToFloat(parserResult);
Note-icon.png

Note: Floating point constants in expressions must have a point as decimal separator, not a comma as used in some European countries. If your expression string comes from user input and contains decimal commas you have to replace the commas by points first before assigning it to the parsers's Expression.

An expression with a variable

In this example, we calculate the value of sin(x)*cos(2*x) for x = 0.5.

Defining variables

At first we have to define the variables. We have only one, x. The parser has a method AddFloatVariable to declare a floating point variable; there are also methods

  • AddBooleanVariable
  • AddStringVariable
  • AddDateTimeVariable

for boolean, string and date/time variables, respectively.

Each one of these methods expects the name of the variable along with its default value. For our sample function we just call:

  FParser.Identifiers.AddFloatVariable('x', 0.5);

0.5 is entered here as a default value because that is the argument at which we want to calculate the expression (it will be shown below how to modify a variable). From now on, the parser will use this number whenever it finds the variable x in the expression.

Of course, you can add other names, e.g. constants like e, etc. (The number pi is already built-in).

Defining the expression

In the next step, the expression string has to be passed to the parser:

  FParser.Expression := 'sin(x)*cos(2*x)';

It is essential to call this after setting up of the variables because the parser needs to know the variables for analyzing the expression.

Calculating the expression

This is done as before with the constant expression - here is a complete procedure which shows the equation and its result in a message box:

var
  FParser: TFPExpressionParser;
  resultValue: Double;
begin
  FParser := TFPExpressionParser.Create(nil);
  try
    FParser.BuiltIns := [bcMath];
    FParser.Identifiers.AddFloatVariable('x', 0.5);
    FParser.Expression := 'sin(x)*cos(2*x)';
    resultValue := FParser.Evaluate.ResFloat;  // or: resultValue := ArgToFloat(FParser.Evaluate);
    ShowMessage(FParser.Expression + ' = ' + FloatToStr(resultValue));
  finally
    FParser.Free;
  end;
end;

Changing variables

So far, x always has the value 0.5 - it behaves like a constant, we could have used the expression 'sin(0.5)*cos(2*0.5)' as well.

To make it behave more like a "variable", we now calculate the test function for the x values between -10 and 10 at integer steps.

The main question is: How to replace the value assigned to a variable? There are several possibilities - all of them require the internal variable Identifier (type TFPExprIdentifierDef) which exposes various ways to access variables and their properties:

  • Use the return value of the AddFloatVariable function.
  • Seek an identifier by calling FindIdentifierByName with the variable name as a parameter.
  • Access the identifier from the Identifiers collection of the parser by using the known index of the variable: We had added x as the only variable, therefore, it must be at index 0.

Once the Identifier is known, the value of the variable can be changed by accessing the property AsFloat (or AsDateTime etc. accordingly):

var
  FParser: TFPExpressionParser;
  argument: TFPExprIdentifierDef;
  s: string;
  x: integer;
  f: double;
begin
  s:='';
  FParser := TFPExpressionParser.Create(nil);
  try
    // Enable the use of mathematical expressions
    FParser.BuiltIns := [bcMath];

    // Add the function argument
    argument := FParser.Identifiers.AddFloatVariable('x', 0.0);

    // Define the function, using the argument name x as defined above
    FParser.Expression := 'sin(x)*cos(2*x)';

    // Calculate some function values
    for x := -10 to 10 do
    begin
      argument.AsFloat := x;                             // Set the function argument value
      f := FParser.Evaluate.ResFloat;                    // Calculate the function value
      s := s + format('x[%d]:[%g]' + LineEnding, [x,f]); // Demo output to display the result
    end;

    // Show the result
    ShowMessage(s);

  finally
    FParser.Free;
  end;
end;

Operators

The expressions discussed above show that standard operators +, -, *, /, <, <=, etc., can be used to setup an expression. Additionally, in recent FPC versions, the operator ^ is available for calculating the power, and mod for the remainder of integer divisions (modulo).

Aggregate functions

In addition to "normal" function the parser supports also "aggregate" functions which are repeatedly applied to a variable, e.g. sum(x) which adds up all the values assigned to the variable x. These functions are available:

  • min(x) - Calculate the minimum of all values assigned to x
  • max(x) - Calculate the maximum of all values assigned to x
  • sum(x) - Calculate the sum of all values assigned to x
  • avg(x) - Calculate the average of the values assigned to x
  • count(x) - Count the numbers assigned to x

In order to have aggregate functions available the category bcAggregate must be added to the BuiltIns of the parser. Next step is to define a variable to which the aggregate function will be applied. The aggregation process must be initialized by calling the parser method InitAggregate; and whenever the variable value is changed the method UpdateAggregate must be called.

Here is an example which calculates the sum of the elements of an array:

uses
  fpexprpars;

const
  Data: array[0..5] of Double = (1.221, 3.4, -1.0, -0.221, -3.0, -0.4);
var
  FParser: TFPExpressionParser;
  xVar: TFPExprIdentifierDef;
  x: Double;
begin
  FParser := TFPExpressionParser.Create(nil);
  try
    FParser.BuiltIns := [bcAggregate];
    xVar := FParser.Identifiers.AddFloatVariable('x', 0);
    FParser.Expression := 'sum(x)';
    FParser.InitAggregate;
    WriteLn('Sum of');
    for x in Data do
    begin
      xVar.AsFloat := x;
      WriteLn(xVar.AsFloat:10:3);
      FParser.UpdateAggregate;
    end;
    WriteLn('----------');
    WriteLn(FParser.Evaluate.ResFloat:10:3);
  finally
    FParser.Free;
  end;

  ReadLn;
end.

Adding user-defined functions

The default parser only knows the built-in functions mentioned above. One of the strengths of of the expression parser is that it is very easy to extend to include other functions. This can be done by calling the method Identifiers.AddFunction, e.g.

  FParser.Identifiers.AddFunction('tan', 'F', 'F', @ExprTan);

In this example, we add the function tan(x) by specifying its name as it will be called in the function expressions (first parameter), the type of the result values (second parameter, "F" = float, "I" = integer, "D" = date/time, "S" = string, or "B" = boolean) and the type of the input values (third parameter, same logic). If a function accepts several input parameters the type of each one must be specified, e.g. by 'FF' for two floating point values, or 'FI' for a first float and a second integer parameter. The last parameter points to the function which is called whenever "tan" is found in the expression string. Since this function has a particular syntax we have to implement it in our own source code:

procedure ExprTan(var Res: TFPExpressionResult; Const Args: TExprParameterArray);
var
  x: Double;
begin
  x := ArgToFloat(Args[0]);
  Res.resFloat := tan(x);
end;

The result of the calculation is returned as parameter Res which is of the TFPExpressionResult type that we met above. The arguments for the calculation are passed by Args which is just an array of TFPExpressionResult values - again because parameters can have several data types. The word Result in TFPExpressionResult is maybe a bit misleading here, because this array holds all the *input* parameters as specified by the input types of the AddFunction method.

When, in fpc 3.2 or later, the input parameter symbol string of the AddFunction method ends with a '+' then parameters with the previous type can be repeated as often as needed; this way a function with a variable parameter count can be implemented. In the following example, we add the function SumOf which adds up as many values as provided:

procedure ExprSumOf(var Res: TFPExpressionResult; Const Args: TExprParameterArray);
var
  sum: Double;
  arg: TFPExpressionResult;
begin
  sum := 0;
  for arg in Args do
    sum := sum + ArgToFloat(arg);
  Res.ResFloat := sum;
end;

begin
  ...
  FParser.Identifiers.AddFunction('SumOf', 'F', 'F+', @ExprSumOf);
  FParser.Expression := 'SumOf(-1,2,3,4.1)';   // arbitrary number of arguments!
  WriteLn(FParser.Evaluate.ResFloat:0:3);
  ...

Some special code

Can I change the built-in function sin(x) to accept arguments in degrees, instead of radians?

Yes. All built-in functions are collected in the instance BuiltInIdentifiers of class TExprBuiltInManager. Find the built-in identifier (BuiltInIdentifiers.Find('sin'), delete it and replace it by a user-defined function having the requested behavior. In FPC 3.2 or later, the identifier can be removed directly (BuiltInIdentifiers.Remove('sin')), in order versions the BuiltInIdentifiers must be cast to a descendant of TExprBuiltInManager in order to access the Delete method of its protected collection Defs:

uses
  Math, fpExprPars;
 
// these are needed only for fpc before v3.2
{
type
  TMyBuiltinManager = class(TExprBuiltinManager);
var
  idx: Integer; 
}
 
var
  parser: TFPExpressionParser;
 
  Procedure ExprSin(Var Result: TFPExpressionResult; Const Args: TExprParameterArray);
  begin
    Result.resFloat := Sin(DegToRad(ArgToFloat(Args[0])));  // convert radians to degrees
  end;
 
begin
  // fpc 3.2+
  BuiltInIdentifiers.Remove('sin');
  // or in older versions:
{ idx := BuiltinIdentifiers.IndexOfIdentifier('sin');
  TMyBuiltinManager(BuiltinIdentifiers).Defs.Delete(idx); 
}
  BuiltinIdentifiers.AddFunction(bcMath, 'sin', 'F', 'F', @ExprSin);
 
  parser := TFPExpressionParser.Create(nil);
  try
    parser.BuiltIns := [bcMath];
    parser.Expression := 'sin(45.0)';
    WriteLn(parser.Evaluate.ResFloat:0:5);
    parser.Expression := 'sin(90.0)';
    WriteLn(parser.Evaluate.ResFloat:0:5);
    parser.Expression := 'sin(180.0)';
    WriteLn(parser.Evaluate.ResFloat:0:5);
  finally
    parser.Free;
  end;
               
  WriteLn('Press ENTER to close.');
  ReadLn;
end.