Parse formula

Home

4D v20 R7

Parse formula


Parse formula ( formula {; options}{; errorMessage} ) -> Function result

Parameter	Type	Description
formula	Text	Plain text formula
options	Longint	Instructions for input / output
errorMessage	Text	Error message (empty string if no error)
Function result	Text	Transformed formula (plain text)

Description

The Parse formula function analyzes the 4D formula, checks its syntax, and returns its normalized form. This allows the formula to remain valid in the event that a 4D language or structure element (command, constant, table, field, or 4D Plugin) is renamed.

Parse formula can be used to evaluate and translate formulas in the following manner:

"Real" table/field names can be converted to "virtual" structure* names (custom names) or tokenized equivalents**
Tokenized table/field equivalents can be converted to virtual structure names or real table/field names
Virtual structures can be converted to real table/field names or tokenized equivalents
4D language elements can be converted to tokenized 4D language equivalents
Tokenized 4D language equivalents can be converted to 4D language elements

* Virtual structures are defined using the SET TABLE TITLES and SET FIELD TITLES commands (* parameter required).

** Tokenized equivalents are 4D language and structure elements in plain text expressed with token syntax as shown below (see also Using tokens in formulas):

[Table:1]Field:1+String:C10(1)

In formula, pass a formula in plain text. It can use real or virtual structure names, as well as tokenized equivalents.

No matter the name types used in formula, by default Parse formula returns the actual 4D language or structure element names without text tokens.

The optional options parameter allows you to specify how formula is expressed and/or returned using the following constants from the Formulas theme. You can combine constants to designate both the input and output format of the returned formula.

Constant	Value	Comment
Formula in with virtual structure	1	Formula contains custom (virtual) names. By default, returned formula contains real names.
Formula out with virtual structure	2	Returned formula must contain custom (virtual) names.
Formula out with tokens	4	Returned formula must contain text tokens (e.g. :Cxx).

The optional errorMessage parameter will receive an error message if there is a syntax error in formula. If there is no error, an empty string will be returned.

Example 1

 ARRAY TEXT($t1;1)

 ARRAY LONGINT($t2;1)

 $t1{1}:="Virtual table"

 $t2{1}:=1

 SET TABLE TITLES($t1;$t2;*)

 

 ARRAY TEXT($tf1;1)

 ARRAY LONGINT($tf2;1)

 $tf1{1}:="Virtual field"

 $tf2{1}:=2

 SET FIELD TITLES([Table_1];$tf1;$tf2;*)

 

  //Virtual structure to table and field name equivalent

 $parsedFormula:=Parse formula("[Virtual table]Virtual field";Formula in with virtual structure;$errorMessage)

  //return [Table_1]Field_2

 

  //Table and field name to virtual structure equivalent

 $parsedFormula:=Parse formula("[Table_1]Field_2";Formula out with virtual structure;$errorMessage)

  //return [Virtual table]Virtual field

 

  //Table and field name to the tokenized form equivalent

 $parsedFormula:=Parse formula("String([Table_1]Field_2)";Formula out with tokens;$errorMessage)

  //return String:C10([Table_1:1]Field_2:2)

Example 2

  //ask the user to type their favorite formula

 $formula:=""

 EDIT FORMULA([Table_1];$formula)

 

  //save user's formula for later use

 CREATE RECORD([users_preferences])

 $persistentFormula:=Parse formula($formula;Formula out with tokens)

 [users_preferences]formula:=$persistentFormula

 SAVE RECORD([users_preferences])

 

  //later: execute the previously saved formula

 CREATE RECORD([Table_1])

 EXECUTE FORMULA([users_preferences]formula)