Expressions
Expressions in @MenuBuilderBot 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 (Macros), 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 | 📂ButtonsPackage 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
Typing in Expressions
In general, the data that Expressions are working with, can be text or numeric.
IMPORTANT: in Expressions, for correct work with text data, they must be enclosed in "" (quotation marks).
The data type is defined in the Expression itself, or by the data type of the Variable used in this expression. Sometimes, in the Expression there is a need to work with initially numeric data as with text.
Learn more about Variables and their types.
In Expressions, you can use:
1. Numeric values with "." point for decimal fractions:1100100.990.81
2. Values of Numeric Variables (balance etc.) using their macros:
For example: %balance%
3. System macros with numeric values (Ref. System, etc.):
For example: %refcount%
4. Values of Text Variables or macros (if the expression uses a Function that works with text (see below))
For example: %firstname%
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
This type of rounding can work with negative numbers (who needs it and why is hard to say, but it can).
For example: {round(12345678, -5)} = 12300000
The function round() cannot add digits to an existing number. To add digits, use the function format_num() (see below).
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 forbool_symb()can be equally applied tobool_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 textbool_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
ERRORS: If instead of the result the function shows:--1- - the number of parameters is bigger than allowed (20)--2- - the number you specified is a fractional number (use only integers)--3- - the number you specified is less than 0 (zero) or greater than the number of parameters you set
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:
Google Search:find - variable that contains the text "menu builder bot".
Link:
https://www.google.com/search?lh=en&q={replace("%find%", " ", "+")}
Result (replacing spaces with "+" characters):
https://www.google.com/search?hl=en&q=menu+builder+bot
Spaces in links can be replaced with the %20 URL code.
For example: {replace("%find%", " ", "%20")}
• Example 2 - Text:
replace("Menu_Builder_Bot", "_", "") ➨ Menu Builder Bot
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:
Google Search:find - variable that contains the text "menu builder bot".
Link:
https://www.google.com/search?lh=en&q={urlencode("%find%")}
Get (replacing spaces with Unicode characters):
https://www.google.com/search?hl=en&q=menu%20builder%20bot
link()
A function to create a text hyperlink in your bot's menu messages.
Now the links you created can be copied along with the rest of the markup of the message, and in the final version the link will be displayed correctly.
link("A", "B")
A - link text
B - link address
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
trueif the string contains ONLY digits andfalseif 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. The function format_num() - CANNOT reduce the number of digits, to reduce (round off), use the function round() (see above).
CASE: Convert a 12-digit number into a 9-digit number.
If you simply round it off {round(0.000000124278753, 9)} = 0.00000012 (we get a number with 8 digits, not 9).
To get 9 digits as a result, first round the number to 9 digits, and only then set its format: {format_num(round(0.000000124278753, 9), 9)} = 0.000000124 (we get 9 digits).
• 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 of working with Date and Time
See dedicated page about working with Date and Time.
❖ Functions "Chewed Magic"
for Einsteins and their Friends
addl()
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)}
Set the flag in cell #2 (for example, buying access to number 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%')}.
❖ Additional Information
Expressions in Conditions.
Read more about Conditions in a separate guide.
• • •
Date and Time Variables in Expressions.
Applicable only if the function of Time variable returns a number as a result of processing.
Read more about Date andTime variables and how to work with them in the Time Variables Guide.