Expressions

Expressions allow you to perform simple mathematical calculations directly in your bot messages, in the Conditions and buttons, as well as in Actions. In expressions, you can use constants, numeric variables, as well as functions of Date and Time variables.

This guide describes the solely principles and mechanics of working with Expressions. Whether the Expressions you use will work in this or that place of your bot depends either on the purchase of the corresponding extensions or Tokens.

Macros and Expressions for Button.
Let you use expressions in buttons.
To connect, go in your bot:
`☞ 🔐Admin | 🧩Extensions | 📂Buttons`

Package of Tokens of Function.
Some Expressions consume Tokens of Functions.
To connect, go in your bot:
`☞ 🔐Admin | 🧩Extensions | 📂Actions`

❖ How does Expressions Look like

Expression must be enclosed in braces `{expression}`. Nesting expressions into one another is not allowed.

All necessary values and operations must be in one expression, enclosed in curly braces. You can use spaces inside expressions if you like - they will be ignored. Use parentheses "()" if you need to perform multiple independent calculations in one expression.

For example:
1. `{2+3}` ➨ 5
2. `{2*3 + 5}` ➨ 11
3. `{(10-1) * (11-2)}` ➨ 81
4. `{%balance% * 67 * 1.02}` ➨ Depends on the state of the user's balance

❖ Allowed Values

In Expressions, you can use:

1. Numeric values ​​with "`.`" point for decimal fractions:
`1`
`100`
`100.99`
`0.81`

2. Values ​​of Numeric Variables (`balance` etc.) using their macros:
`%balance%`
`%my_variable%`

3. System macros with numeric values ​​(Ref. System, etc.):
`%refcount%`
`%userid%`

4. Values of Text Variables (if the expression uses a Function that works with text (see below))

REMINDER: Values of Text Variables or any other text in Expressions must be "quoted". See examples below.

❖ Available Operations

You can use the following operations (the list may be expanded in the future):

1. Mathematical operators: `+`, `-`, `*`, `/`
`{2 + 1}`, `{3 * 3}`

2. Unary operators: `+`, `-`
`{-1 * 3}`

3. Division rounded down to the nearest integer:
`{10 // 3}` ➨ 3

4. Power (x to the power of y): `**`
`{2 ** 5}` ➨ 32 (2 to the power of 5)
`{pow(2, 5)}` ➨ 32 (same notation only with function)

Use the "`pow(x, y)`" function if "`**`" breaks markdown formatting.

❖ Math Functions

`min(A, B, C, D)`
Will select the minimum value from the list.

The maximum length of the list is 20 values. If the list is longer, it will always return 0 (zero).

`max(A, B, C, D)`
Will select the maximum value from the list.

The maximum length of the list is 20 values. If the list is longer, it will always return 0 (zero).

`mod(A, B)`
Returns the remainder after dividing two numbers.

❖ Rounding Functions

`round(xxx.xx)`
"Banking rounding" to the nearest integer.
{round (100.01)} = 100
{round (100.99)} = 101

`round(xxx.xx, y)`
"Bank rounding" to "y" decimal places.
{round (100.01, 1)} = 100.0
{round (100.11, 1)} = 100.1
{round (100.99, 2)} = 100.99
{round (100.99, 1)} = 101.0

`floor(xxx.xx)`
Round down to the nearest integer (whole number).
{floor (100.11)} = 100
{floor (100.99)} = 100

`ceil(xxx.xx)`
Round up to the nearest integer (whole number).
{ceil (100.11)} = 101
{ceil (100.99)} = 101

❖ Random Values

`randi(A, B)`
Random integer between A and B (including A and B).

`randf(A, B)`
Random fractional between A and B (including A and B).

`rands()`
Random sign - number "1" with random sign: -1 or +1.
Special function for expression {randi(0,1) * 2 - 1}

`randl(A, B, C, D)` - for numbers.
`randl("A", "B", "C", "D")` -  for text.
Random list - random VALUE from the given list.

It can work with both Numbers and Text. When using text, it must be enclosed in quotation marks.
The maximum length of the list is 20 values. If the list is longer, it will always return 0 (zero).

When used in an expression, `randi(A, B)` will be replaced with a random number and you can apply any other supported operators / functions to it.

Example of usage in post:
You got `{randi(1,10) * 2}` apples

❖ String Functions

bool_symb() and bool_symbn()

Boolean to Symbol and Boolean to Symbol New - allow you to change the text in a message, condition or inline button, depending on whether the specified condition is met or not.

The function `bool_symbn()` (Boolean to Symbol New), unlike it, `bool_symb()` shows the result from a New Line, but only if the result is not empty - this allows you to set several consecutive Expressions in ONE line, but the result will be arranged in a column of exactly the same height as you need, without empty lines... All abilities described for `bool_symb()` can be equally applied to `bool_symbn()`.

ATTENTION: the function consumes 0.1 "Token of Functions". If Tokens are not available will show "`---`" (dashes).

`bool_symb((A), "B", "C")` - with quotation for text
`bool_symb((A), B, C)` - without quotation for expressions
Where `A` is a Condition
If `A` is TRUE or 1 (True), will show the `B` - string / expression.
If `A` is FALSE or 0 (False), will show the `C` - string / expression.

`bool_symb()` can be used in message's texts, in Expressions and Inline Button titles.

This function can work with both String (text) and Numeric data. If a number is passed as parameters "B" or "C", then result can be used in calculation of math expression. The parameter in "B" and "C" can be formed in different ways: as text, number, variable's macros, math expression.
IMPORTANT: each separate parameter "B" and "C" can accept and process only ONE type of data: either Text or Number (you cannot combine them IN ONE parameter), regardless of the way, from the listed above, this data was actually transmitted into this parameter.

• Example 1: If you need to show two types of messages (text):
`{bool_symb((%mynum% == 1), "✅", "❌")}`
If the value of the variable mynum is 1, it will show ✅, otherwise ❌.

• Example 2: When you want to show a message (text) only if the condition is true, leave the second quotes empty:
`{bool_symb((%mynum% == 1), "✅", "")}`
If mynum is 1, it will show ✅, otherwise it will show nothing.

• Example 3: When it is necessary to show a message (text) only if there is data in the Numeric variable:
`{bool_symb((%mynum% != 0), "✅", "")}`
If there is any numeric data in the mynum variable , it will show ✅, otherwise it will show nothing.

• Example 4: When you want to show a message (text) only if there is data in the Text variable:
`{bool_symb(("%mytext%" != ""), "✅", "")}`
If there is any text data in the mytext variable , it will show ✅, otherwise it will show nothing.

• Example 5: When you need to use an Expression instead of text:
`{bool_symb((%mynum% == 0), "❌", %var1% + %var2%)}`
If mynum is `0`, it will show ❌, otherwise it will show the result of `%var1% + %var2%` expression.

More interesting ways of using `bool_synb()` you can find in this Tutorial.

int_symb()

Integer to Symbol - allows you to replace the numbers of numeric value passed to it, with the specified symbols in the appropriate quantities. Allows you to set the maximum number of characters to be displayed.

ATTENTION: the function consumes 0.1 "Token of Functions". If Tokens are not available will show "`---`" (dashes).

`int_symb(A, "B", C)`
Where A is the passed numeric Value (can be a numeric variable).
B is the Character to replace the number of the passed Value.
C is the maximum number of Characters to display in a message.

• Example 1: will show 5 characters "😀" out of maximum 10:
`{int_symb(5, "😀", 10)}`
Result : 😀😀😀😀😀

• Example 2: will show 10 characters "😡" out of maximum 10 despite the fact that the transmitted Parameter is 15, the remaining 5 characters will be displayed in numbers:
`{int_symb(15, "😡", 10)}`
Result : 😡😡😡😡😡😡😡😡😡😡 +5

• Example 3: Numeric variable %num% contains 5 as its value. Thus, the function will show 5 characters "🤯" out of maximum 10:
`{int_symb(%num%, "🤯", 10)}`
Result : 🤯🤯🤯🤯🤯

More interesting ways of using `int_synb()` you can find in this Tutorial.

num_symb()

Numeric to Symbol - takes the value of a NUMERIC variable and, depending on the number specified in it, displays the specified text.

ATTENTION: the function consumes 0.1 "Token of Functions". If Tokens are not available will show "`---`" (dashes).

`num_symb(A, "X", "Y", "Z")`
Where A is a macros of Numeric variable.
X, Y, Z - Text data that needs to be substituted.

Numbering starts from 0 (zero)
Maximum number of arguments: 10.
If the number in the variable is greater than 9, the function will not show anything.

Example 1: in the variable var_name - 1
`{num_symb(%var_name%, "XXX", "YYY", "ZZZ")}`
Result: YYY

• Example 1: in the variable var_name - 1 or 3
`{num_symb(%var_name%, "XXX", "", "ZZZ")}`
Result: will not show anything

len()

Function that allows you to find out the length of a string - the data given to it, will be converted into a string format, the length of the string will be returned as a result.

`len(A)` - for numerical data.
`len("B")` - for text data.
A - numeric data or Numeric variable.
B - any data (including Numeric variable data).

"Space" characters in strings are also counted in total number of characters.

• Example:
len(777) 3
len("ololo-5") 7

startswith()

A function that allows you to check the beginning of a string for a match - the data given to it, will be converted into a string format, the beginning of the string is checked against the specified text. True / False is returned as a result.

`startswith("A", "B")` - any data in quotes (as text).
A - data for analysis (text or numeric).
B - verification data.

Only the BEGINNING of a line is checked.

The case of characters matters.

• Example 1 - text:
startswith("MYname", "MY") True
startswith("MYname", "my") False
startswith("notMYname", "MY") False

• Example 2 - variable macro:
startswith("%variable%", "123") - the contents of the variable is compared.

in_str()

A function that allows you to check for the presence of specified characters or words in the text of a variable. True / False will be returned as a result.

`in_str("A", "B")` - any data in quotes (as text).
A - data for analysis (text or numeric).
B - verification data.

The case of characters matters - in general case. in conditions all symbols converted to lower case.

• Example 1 - text:
in_str("MYname", "MY") ➨ True
in_str("MYname", "my") ➨ False

• Example 2 - variable macro:
in_str("%variable%", "123") - the contents of the variable is compared.

in_list()

The function checks whether the first value, presented among the list of other values. True / False is returned as the result.

`in_list("A", "B1", "B2", "B3")`
A - some value.
B1, B2, B3 - list of values for comparison.

You can use any macros or text you specify as the values of "A" and "B".
The maximum length of the list is 20 elements.

replace()

The function allows you to replace any combination of characters in the "string" with the one you specified.

It is convenient, for example, to form GET requests by replacing spaces with "+" signs in search queries of different websites. In general, the range of application is not limited by links.

`replace("A", "B", "C")` - any data in quotes (as text).
A - data for analysis (text or numbers as text).
B - the sequence of characters to be replaced.
C - what you need to replace the found with.

The maximum length of the text to search is 500 characters.
The maximum length of the replacement text is 25 characters.

• Example 1 - GET Request:
`find` - variable that contains the text "menu builder bot".
https://www.google.com/search?lh=en&q=`{replace("%find%", " ", "+")}`
Result (replacing spaces with "+" characters):

• Example 2 - Text:

urlencode()

The function allows you to convert text to Unicode codes and form correct strings for URL addresses.

`urlencode("A")` - any data in quotes (as text).
A - data to be converted (text or numbers as text).

The maximum length of text to be converted is 500 characters.

• Example 1 - GET Request:
`find` - variable that contains the text "menu builder bot".
https://www.google.com/search?lh=en&q=`{urlencode("%find%")}`
Get (replacing spaces with Unicode characters):

`link("A", "B")`

• Example:

Both parameters of `link()` function, must be enclosed in "quotation marks".

vget() and vgetn()

A functions to get the values of variables. Both functions accept text as a variable's name, macros of other variables can be used in the text.
vget() - returns the data of a variable in TEXT format - regardless of the format and content of the variable itself.
vgetn() - returns the data of a variable in NUMERIC format - regardless of the format and contents of the variable itself. If the data in the variable cannot be represented by numbers, it will return "---" (an error).

IMPORTANT: The function `vget()` can accept data from ANY type of variable, but it always returns data in TEXT format (even if it is numbers). In other words: takes anything - returns TEXT. For that reason, the data received from it cannot be used in calculations - it can only be compared with another text.

IMPORTANT: The function `vgetn()` can accept data from ANY type of variable, however, it always returns data in NUMBER format (even if it is the data of a text variable containing numbers). In other words: takes anything - returns a NUMBER. For that reason, the data received from it can be used in calculations and comparisons.

The main feature of these functions is that the name of the variable whose value has to be obtained is composed using text, system macros, as well as macros of other variables. Thus, using the same function in the message, you can access different variables depending on the state and value of other user's variables.

`vget("A")` and `vgetn("A")`
`vget("A%M%A")` and `vgetn("A%M%A")`
A - the text of the variable name (or part of it)
M - the name of a system macros or another variable (like any macros - enclosed in %percent% signs)

Parameters of functions `vget()` and `vgetn()` (variables names) are text and must be enclosed in "quotation marks".

Example 1: Forming a variable name for querying data.
The value of `%num%` is 1;
vget("var%num%") %var1% (formed variable name)
vget("var%num%txt") %var1txt% (formed variable name)

Example 2: Display of the same value by both functions.
The text variable `%var1%` value is "xxx";
vget("var1") %var1% xxx (shows text)
vgetn("var1") %var1% --- (shows an error)

The text variable `%var2%` value is "555";
vget("var2") %var2% 555 (as text)
vgetn("var2") %var2% 555 (as a number)

The two presented functions simply open the "Universe" to create universal functionality, based on completely different principles. From the outside, it may not look like this, but whoever understands is will appreciate the opportunities that have opened up. If you don't understand, we are sorry, but it's almost impossible to explain.

is_digit()

A function that returns `true` if the string contains ONLY digits and `false` if the string contains any characters other than digits.

`is_digit("A")`
A - any String (text or variable value)

• Example 1 (syntax):
is_digit("55555") ➨ True
is_digit("55555aaaaa") ➨ False

• Example 2 (condition):
{is_digit("55555") == True} - Condition is true
{is_digit("55555")} - the same, only abbreviated notation

Variable Macros can be used as an argument.

as_num()

The function converts string values to numeric values.

The function performs two kinds of actions:
1. Allows you to use the data of text variables containing numeric values in Expression's calculations.
2. Converts invalid text format numbers to valid math numbers (for example: 01 will be shown as 1).

❖ Functions of working with numbers

format_num()

The function of formatting the output of the number in the message. Allows you to add zeros to the number of digits both to the left of the integer part and to the right of the fractional part - ignoring the rules of the standard mathematical notation.

ATTENTION: the function consumes 0.1 "Token of Functions". If Tokens are not available will show "`---`" (dashes).

`format_num(A, B, C)`
A - is the number itself.
B - the number of digits in the fractional part.
C - the number of digits in the integer part (optional).

• Example 1: whole and fractional:
format_num(1, 6, 2) = 01.000000
format_num(1.23, 6, 2) = 01.230000
format_num(0.1234, 6, 2) = 00.123400

If the number of digits in the original number is bigger than specified in the function, they will remain unchanged.

• Example 2: the number of digits is bigger than specified in the function:
format_num(12.345678, 4, 1) = 12.345678

If there is no need to format the integer part, the third parameter is set to zero or not indicated at all.

• Example 3: only fractional with and without parameter:
format_num(1, 4, 0) = 1.0000
format_num(1, 4) = 1.0000
format_num(1.23, 4, 0) = 1.2300

format_num(1.23, 4) = 1.2300

abs()

A function that returns the modulus of a number - will always return a POSITIVE number, even if the variable contains a negative number.

It is mainly needed for formatting user input - so that users cannot use a negative number where it is not allowed, or to exclude a human factor of data entry errors.

`abs(A)`
A - is a number.

• Example: The value of the variable `num` is `-5`;
abs(%num%) ➨ 5

❖ Functions "Chewed Magic"for Einsteins and their Friends

Add Loop - Adding a value with cyclic overflow. Allows you to loop through the values ​​with the specified parameters by running them in a circle and resetting the value when the specified maximum is reached.

`addl(A, B, C)`
A - is the current number.
B - added number (`delta`).
C - overflow boundary (`limit`).

Let's take a look at how the function works using the clock as an example:
`{add_loop(20, 10, 24)}` == 6
In the example above, it is now 20 hours (20:00 military = 8pm), we add 10 hours, the maximum number of hours in a day is 24 - so the overflow (`limit`) is 24. So 20 (20:00 military) + 10 hours (`delta`) we get 6 (06:00 military = 6am). The function, passing the threshold of 24 hours, resets the number to 0 (zero) and continues from there.

• Example 1: sequential search (with a step of 1) numbers from 0 to 4 for a BONUS button that adds value.
`{-1 * %num% + addl(%num%, 1, 4)}`
What happens in the expression:
`{-%num% + (%num% + 1)}` == 1
Bonus button for a variable `%num%` with such an expression for accrual each time it is pressed, it will sequentially write the results 0, 1, 2, 3, 4, 0, 1... and so on, in a circle. The result of each step must be written to a variable, `%num%` changing its value.

Further analysis of the function is NOT necessary for EVERYONE! If you don’t care how it works, or you have read it and didn’t understand anything, just use the above expression for the bonus buttons and don’t bother yourself.

Let's analyze the behavior of the function... the part of the expression `{-1 * %num%}` as a result of the calculation will give a negative value of the variable `%num%` itself (in general, you can use the expression `{-%num%}`, it will give the same result).

What is it for?

The end result of the expression should be one number that the Bonus button will ADD to the existing one in the variable it is configured to work with. The bonus button always only adds values - this is the way its mechanics work (for Actions where it is possible to directly assign (set) a value to variables, all these difficulties are not needed).

As a result of the calculation in the expression `{addl (%num%, 1, 4)}` we get the sum of the current value of the `%num%` variable and the 1 (`delta`), which is our function step. If the Bonus button simply adds a new expression value to the variable, we will get a result greater than what we want `{%num% + (%num% + 1)}`, which is not what we want. Therefore, before the bonus button adds the result to the variable, the value already existing in the variable must be subtracted from this amount, so the Bonus button will add only the remainder (the difference). The easiest way to do this is by adding the sum to the negative value of the variable itself - because adding with a negative number is equivalent to subtracting.

Let's imagine that the current value of `%num%` is 2 (and its next value, respectively, should be 3). Then the expression `{addl (%num%, 1, 4)}`, will look like this: `{addl (2, 1, 4)}` is 2 + 1 = 3. In this case, the bonus button should add the result 3 to the value of the variable already equal to 2, as a result, in the variable, instead of 3, we will get 5. To prevent this from happening, before adding a value using the Bonus button, in the expression itself we first take the negative value of our variable `%num%` and add its value to it increased by 1. Thus, getting 1 as the result of the calculation and the Bonus button adding this value will give us 3 (three) - the desired value in the `%num%` variable.

flag_get(), flag_set(), flag_del()

Setting and using Flags. Numeric variable can be used for Flags. While using as a flag variable, you can look at the value of the variable, but there is no practical sense. One variable can contain up to 30 flags.

Find out if there is a flag in a variable

`flag_get(A, B)` - Main notation.
A - Macros of variable name.
B - serial number of the flag from 1 to 30.

Returns 0 (zero) if there is no flag and > 0 if there is a flag.

Where to use: Messages in conjunction with `bool_symb()`, `bool_symbn()` the conditions of buttons and Actions.

• Example 1: condition on the button
`{flag_get(%subscription%, 1) != 0}`
If cell #1 is not equal to zero and it contains a flag, then the user is subscribed to mailing list #1

• Example 2: condition on the button
`{flag_get(%subscription%, 2) == 0}`
If there is no flag in cell #2, then the user is NOT subscribed to mailing list #2

Set a flag in a variable

`flag_set(A, B)`
A - Macros of variable name.
B - serial number of the flag from 1 to 30.

Where to use: buttons for changing values ​​(bonus, exchange1)

• Example 3: free subscription (bonus button, bonus value)
`{flag_set(%subscription%, 1)}`
Set a flag in cell #1 (for example, subscribe to newsletter number 1).

• Example 4: buying access (button exchange1, as the value of the accrual)
`{flag_set(%subscription%, 2)}`

• Example 5: To avoid a double purchase, it is better to use the condition
`{flag_get(%subscription%, 2) == 0}`
Check if there is a flag in cell #2 and if not, then allow further actions.

Clear the flag in variable

`flag_del(A, B)`
A - Macros of variable name.
B - serial number of the flag from 1 to 30.

Where to use: bonus buttons, may be exchange1 if you know why...

• Example 6: Unsubscribe from mailing
`{flag_del(%subscription%, 1)}`
Will remove the flag in cell #1 (Unsubscribe from mailing list number 1)

❖ Message Examples

Example 1:
Your balance {%balance% * 100} USD

Example 2:
You have %refcount% referrals. Contact us and you will get 0.5\$ for every 10 referrals and 2\$ bonus for every 100 referrals. In total you get: {%refcount%//10 * 0.5 + %refcount%//100 * 2}.

❖ Restrictions

Expressions cannot be placed inside another expressions (no nesting).

An example of an invalid expression:
{a + {b + c}}
The provided expression is "Nested" and will not be parsed correctly. All incorrect expressions will be left unprocessed or may be partially processed - in any case, the result will be incorrect.

Use parentheses "()" if you need to perform several independent calculations in one expression.
An example of a correct expression:
`{a + (b + c)}`

• • •

In expressions, use "." (Period) rather than "," (comma) as a decimal separator.

An example of an invalid expression:
{x, xx + x, xxx}
Such an expression will not be parsed and will be shown in its original form in the message.

An example of a correct expression:
`{x.xx + x.xxx}`

The quotation marks of the expression working with the text of the Text Variables and the quotation marks inside the Text Variable itself - shall be different.

Example:
`{len("%text%")}` - counting the number of characters in the `%text%` variable.
If the text saved inside the `%text%` variable contains quotes: `""`, then in the expression itself, you can use another kind of quotes, for example, single quotes: `''`. So the expression will look like this:
`{len('%text%')}`.