Skip to content

Commit

Permalink
Added documentation for exprtk attribute on <property> elements.
Browse files Browse the repository at this point in the history
  • Loading branch information
@end2endzone
end2endzone committed Oct 31, 2020
1 parent dc3c459 commit 7bfe79d
Showing 1 changed file with 32 additions and 1 deletion.
33 changes: 32 additions & 1 deletion UserManual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -784,7 +784,7 @@ For example, the following sets the property `myprogram.user.name` to an empty v

#### value attribute: ####

The `value` attribute defines the actual new value of the given property.
The `value` attribute defines the new value of the given property.

For example, the following set the property `myprogram.user.name` to value `Al Coholic` :
```xml
Expand All @@ -793,6 +793,37 @@ For example, the following set the property `myprogram.user.name` to value `Al C



#### exprtk attribute: ####

The `exprtk` attribute defines an expression that is evaluated to set a new value for the given property. The expression must be specified as a mathematical expression and the result must evaluates to an integer or a floating point value such as `4+9` or `${foo}+1`.

The `exprtk` attribute can also be set to an expression that evaluates to `true` or `false` and logical `and` and `or` operators can be use to group expressions. eg: `${foo.count} > 1 and '${foo.state}'=='PAUSED'`.

The attribute supports the following operators:
* Basic operators: `+`, `-`, `*`, `/`, `%`, `^`
* Equalities & Inequalities: `=`, `==`, `<>`, `!=`, `<`, `<=`, `>`, `>=`
* Logic operators: `and`, `not`, `or`, `xor`, `true`, `false`
* String operators: `in`, `like`, `ilike`, []

Strings may be comprised of any combination of letters, digits special characters including (~!@#$%^&*()[]|=+ ,./?<>;:"_) or hexadecimal escaped sequences (eg: \0x30) and must be enclosed with single-quotes.
eg: `'Frankly my dear, \0x49 do n0t give a damn!'`

The `exprtk` attribute allows advanced property evaluation. The following table show useful expression examples:

| Use cases | Expression | Meaning |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Update a property using a generic equation | \${myvalue}^2 + 5*\${myvalue} + 100 | Evaluate the quadratic equation `x^2 + 5x + 100` where `x` is equal to the value of property `myvalue`. |
| Create a counter using properties.<br>(with a default property value set) | \<property name="mycounter" exprtk="${mycounter}+1"\> | The property update itself by increasing its own value by 1.<br>Note: this only work if the property is defined to a numeric value first. |
| Create a counter using properties.<br>(without initializing the property first) | if ('\${mycounter}' == '$'+'{mycounter}' or '\${mycounter}' == '0') 1;<br>else if ('\${mycounter}' == '1') 2;<br>else if ('\${mycounter}' == '2') 3;<br>else if ('\${mycounter}' == '3') 4;<br>else if ('\${mycounter}' == '4') 5;<br>else if ('\${mycounter}' == '5') 6;<br>else if ('\${mycounter}' == '6') 7;<br>else if ('\${mycounter}' == '7') 8;<br>else if ('\${mycounter}' == '8') 9;<br>else 10; | Increase the value of property `mycounter` by `1` going from `1` up to `10`.<br>On the first call, the first line of the expression detects if the property is unset and set it to `1`. |
| Get the length of a property value. | '\${command}'[] | Set the property to the length of the `command` property value. |
| Set a property to logical `true` or `false`. | ${foo} == 2 or ${bar} >= 5 | The property will be set to value `1` if the expression evaluates to `true` <br>and set to `0` if the expression evaluates to `false`. |


**Note:**
The `exprtk` attribute uses the *exprtk library* to parse the expression. For more details and supported expressions, see the exprtk documentation on the [official github page](https://github.com/ArashPartow/exprtk) or the [library website](http://www.partow.net/programming/exprtk/index.html).



### &lt;file&gt; action ###

The &lt;file&gt; element is used to create a text file on disk. The content of the file is specified between the opening and closing tags of the &lt;file&gt; element. The &lt;file&gt; element supports dynamic properties and can be used to create default configuration files or create support files for the menu.
Expand Down

0 comments on commit 7bfe79d

Please sign in to comment.