Skip to content

What are expressions?

Expressions allow you to perform operations within messages and dynamically modify them, as well as in actions. Some of their uses include performing arithmetic calculations like {2 + 2}, comparison operations like {5 == 5}, representing variables and primitive variables like {balance} or {first_name}, and much more. VisualMaker will always inform you when you can use expressions.

How to use expressions?

Expressions must always be enclosed in braces { }, so VisualMaker understands that you want to use an expression.

Inside them, you can use (or not use) spaces, it's the same {3 + 5} as { 3+5 }.

Types of values

  • strings: literal texts represented within double quotes "this is a text", or single quotes 'this is also a text'.
  • numbers: numbers are represented as is, without quotes, 10 is an integer, 34.87 is also a number, in this case a decimal.
  • dates: dates are strings with a particular format, represented as "DD-MM-YYYY HH:MM:SS.micro" (HH:MM:SS.micro is optional), for example "31-12-2024 23:59:59.123456", internally dates are strings, so they must always be enclosed in quotes.
  • booleans: True when something is true, False when something is false.
  • None: a value that refers to nothing, or does not exist.

Arithmetic operators

Arithmetic operators allow you to perform mathematical calculations within your messages, returning the result of the calculation as a numerical value. The arithmetic operators are as follows:

  • +: addition
  • -: subtraction
  • *: multiplication
  • /: division
  • %: modulo
  • **: exponentiation
  • //: quotient

Comparison operators

Comparison operators allow you to make evaluations, returning True if the comparison is true, or False if it's false. They are as follows:

  • ==: equal to, example: {2 + 1 == 3}, will return True, since 2 + 1 equals 3.
  • !=: not equal to, example: {"hello" != "hello"}, will return False, since hello is not different from hello.
  • >: greater than, example: {10 > 5}, will return True, since 10 is greater than 5.
  • <: less than, example: {2 < 5}, will return True, since 2 is less than 5.
  • >=: greater than or equal to, example: {3 >= 3}, will return True, since 3 is not greater, but equal to 3.
  • <=: less than or equal to, example: {2 <= 3}, will also return True, since 2 is not equal, but less than 3.

Examples of expression use

  • {2 + 5} ➡️ 7 (addition operation)
  • {5 - 1} ➡️ 4 (subtraction operation)
  • {5 * 5} ➡️ 25 (multiplication operation)
  • {8 / 2} ➡️ 4 (division operation)
  • {2 * (3 + 1)} ➡️ 8 (combined operation, you can also use parentheses)
  • {balance == 10} ➡️ True | False (comparison operation equal to, will return True if the value of the balance variable is 10, otherwise will return False)
  • {first_name != "John"} ➡️ True | False (comparison operation not equal to, will return True if the primitive variable first_name is different from John, otherwise will return False)
  • {"28-02-2024" > "28-02-2023"} ➡️ True (comparison operation greater than, comparing two dates, will return True, since the date 28-02-2024 is greater than the date 28-02-2023.)
  • "The result of 3 + 2 is {3 + 2}" ➡️ "The result of 3 + 2 is 5"

Functions

Functions allow you to perform even more powerful operations within expressions. All the functions of VisualMaker are listed below.

Functions receive arguments in parentheses, separated by comma. To call a function, it is done as follows:

function(argument1, argument2)

min()

Receives numbers as arguments and returns the smallest number. There is no limit to the number of arguments.

Arguments: numbers, unlimited.

Example:

{min(5, 7, 2, 6.1, 3)} ➡️ 2

max()

Receives numbers as arguments and returns the highest number. There is no limit to the number of arguments.

Arguments: numbers, unlimited.

Example:

{max(5, 7, 2, 6.1, 3)} ➡️ 7

round()

Rounds a number.

Argument 1: number to round.

Argument 2 (optional): number of decimals the rounded number should have.

Examples:

{round(12.8649)} ➡️ 13

{round(12.8649, 2)} ➡️ 12.86

ceil()

Rounds a number up.

Argument 1: number to round.

Example:

{ceil(8.5649)} ➡️ 9

floor()

Rounds a number down.

Argument 1: number to round.

Example:

{floor(8.5649)} ➡️ 8

random()

Returns a random number between the number in argument 1 and the number in argument 2. The returned number will have a number of decimals similar to the argument with the most decimals.

Argument 1: number to start from.

Argument 2: number to end at.

Examples:

{random(1, 10)} ➡️ 3 (random number between 1 and 10)

{random(1.001, 2)} ➡️ 1.329 (random number between 1.001 and 2, the returned number will have 3 decimals)

absolute()

Returns the absolute value of the number passed as an argument.

Argument 1: number.

Example:

{absolute(-5)} ➡️ 5

pick_one()

Receives any type of elements as arguments and returns one randomly. There is no limit to the number of arguments.

Argument 1: any type of elements.

Example:

{pick_one(5, "text", True, 16)} ➡️ "text" (randomly returned element)

pick_by_index()

Selects an element from a list, tuple, or string using a specified index.

Argument 1: list, tuple, or string from which to choose an element.

Argument 2: index of the element to select, must be an integer number.

Examples:

{pick_by_index(("John", "Mary", 10), 0)} ➡️ "John" (elements passed in tuple format ( ), returns "John", as it is at index 0, the first element)

{pick_by_index(["John", "Mary", 10], 1)} ➡️ "Mary" (elements passed in list format [ ], returns "Mary", as it is at index 1, the second element)

{pick_by_index("text", 3)} ➡️ "t" (single element passed as string, returns "t", as counting characters from left to right, starting from 0 and ending at 3, results in t)

Indexes

Indexes always start from number 0.

startswith()

Returns True if a given text starts with a specific subtext, otherwise returns False.

Argument 1: text to check.

Argument 2: subtext to check if it's the start of the text.

Example:

{startswith("this is a string", "this")} ➡️ True ("this is a string" does start with "this")

endswith()

Returns True if a given text ends with a specific subtext, otherwise returns False.

Argument 1: text to check.

Argument 2: subtext to check if it's the end of the text.

Example:

{endswith("this is a string", "ing")} ➡️ True ("this is a string" does end with "ing")

capitalize()

Returns a copy of the text with the first letter capitalized and the rest in lowercase.

Argument 1: text to capitalize.

Example:

{capitalize("john")} ➡️ "John"

capitalize_all()

Converts the first character of each word in a given text to uppercase.

Argument 1: text to capitalize.

Example:

{capitalize("my name is john")} ➡️ "My Name Is John"

len()

This function returns the length of the provided text, tuple, or list.

Argument 1: string, list, or tuple of which to know the length.

Examples:

{len("this is a string")} ➡️ 16 (it has a length of 16 characters)

{len(("elem1", "elem2", "elem3"))} ➡️ 3 (the tuple has 3 elements)

replace()

Aims to replace all occurrences of a specific string in a given text.

Argument 1: The string to search for and replace in the text.

Argument 2: The string to replace with.

Argument 3: The text where the string to be replaced is found.

Example:

{replace("sunny", "rainy", "Today is a sunny day.")} ➡️ "Today is a rainy day."

slice()

This function aims to perform a slice on a given text, returning a specific portion of it.

Argument 1: The text from which the slice will be performed.

Argument 2: The starting index of the slice. If omitted or provided a `None` value, the beginning of the text will be taken.

Argument 3: The ending index of the slice. If omitted or provided a `None` value, the end of the text will be taken.

Example:

{slice("Hello World", 1, 4)} ➡️ "ell"

is_inside()

Returns True if an element is present within a given container, which can be a tuple, a list, or a string; returns False if it is not.

Argument 1: The element to search for within the container.

Argument 2: The container (tuple, list, or string) in which the search is performed.

Examples:

{is_inside("John", ("John", "Mary", 10))} ➡️ True (checks if "John" is among the elements passed in tuple format ( ))

{is_inside("Pablo", ["John", "Mary", 10])} ➡️ False (checks if "Pablo" is among the elements passed in list format [ ])

{is_inside("ex", "text")} ➡️ True (checks if "ex" is inside "text")

is_string()

Returns True if the argument is a string; otherwise, returns False.

Argument 1: The object to check if it's a string.

Example: {is_string("hello")} ➡️ True

is_numeric()

Returns True if the argument is numeric, i.e., if it can be converted to a floating-point number without errors. If the argument is not numeric, it returns False.

Argument 1: The object to check if it's numeric.

Examples:

{is_numeric(123)} ➡️ True

{is_numeric("3.14")} ➡️ True

{is_numeric("hello")} ➡️ False

is_bool()

Returns True if the argument is a boolean, i.e., if it is True or False. If the argument is not a boolean, it returns False.

Argument 1: The object to check if it's a boolean.

Examples:

{is_bool(True)} ➡️ True

{is_bool("False")} ➡️ False ("False" is in quotes, so it's not a boolean but a string)

to_string()

Converts a given object to its string representation.

Argument 1: The object to convert to a string.

Examples:

{to_string(123)} ➡️ "123"

{to_string(True)} ➡️ "True"

to_number()

Converts the object to a floating-point number. If the conversion is successful, it returns the resulting number.

Argument 1: The object to convert to a number.

Example:

{to_number("3.14")} ➡️ 3.14

to_integer()

Converts the object to an integer. If the conversion is successful, it returns the resulting number.

Argument 1: The object to convert to an integer.

Example:

{to_integer(3.14)} ➡️ 3

to_upper()

Returns a given text in uppercase.

Argument 1: The text to convert to uppercase.

Example:

{to_upper("hello world")} ➡️ "HELLO WORLD"

to_lower()

Returns a given text in lowercase.

Argument 1: The text to convert to lowercase.

Example:

{to_lower("HELLO WORLD")} ➡️ "hello world"

fix()

Adjusts the number of decimals of a given number, removing trailing zeros. Returns a numeric value in number format.

Argument 1: The number whose decimals are to be adjusted. It can be a number or a string representing a number.

Argument 2: The number of decimals to which the number is to be limited.

Examples:

{fix(3.141592653589793, 2)} ➡️ 3.14

{fix(10.124054, 4)} ➡️ 10.124

hardfix()

Adjusts the number of decimals of a given number, keeping trailing zeros. Returns a numeric value in string format.

Argument 1: The number whose decimals are to be adjusted. It can be a number or a string representing a number.

Argument 2: The number of decimals to which the number is to be limited.

Examples:

{hardfix(10.124054, 4)} ➡️ "10.1240"

{hardfix(8.31, 8)} ➡️ "8.31000000"

count()

Returns the number of times the subtext appears within the text.

Argument 1: The text in which the subtext is to be searched.

Argument 2: The subtext to count within the text.

Examples:

{count("hello world", "o")} ➡️ 2

{count("abababab", "ab")} ➡️ 4

find()

Returns the position of the first occurrence of the subtext within the text. If the subtext is not found, the function returns None.

Argument 1: The text in which to search for the subtext.

Argument 2: The subtext to find within the text.

Example: {find("hello world", "world")} ➡️ 6

condition()

Evaluates a condition and returns a value based on whether the condition is True or False.

Argument 1: The condition to evaluate. It must be an expression that can be evaluated as True or False.

Argument 2: The value to return if the condition is True.

Argument 3: The value to return if the condition is False.

Examples:

{condition(5 > 3, "True", "False")} ➡️ "True"

{condition(2 == 7, "it's true", "it's false")} ➡️ "it's false"

date_now()

Returns the current date and time according to a timezone set in the bot. Does not accept arguments.

Example:

{date_now()} ➡️ "01-03-2024 00:07:48.030700"

date_utcnow()

Returns the current date and time according to the UTC timezone. Does not accept arguments.

Example:

{date_utcnow()} ➡️ "01-03-2024 03:08:28.429305"

date_format()

This function formats a date and time into the specified format.

Argument 1: The date and time to format.

Argument 2: The desired format for the date and time. By default, it is 'day-month-YEAR HOUR:minute:second.micro'.
Formats

Use YEAR for the 4-digit year, or year for the 2-digit year.

Use HOUR for 24-hour time, or hour for 12-hour time.

Use time to include AM or PM.

Examples:

{date_format("01-03-2024 00:07:48.030700", "day/month/YEAR")} ➡️ "01/03/2024"

{date_format("01-03-2024 00:07:48.030700", "day, month, YEAR")} ➡️ "01, 03, 2024"

{date_format("01-03-2024 00:07:48.030700", "hour:minute time")} ➡️ "12:07 AM"

{date_format(date_joined, "month-year")} ➡️ "03-24" (according to the date you joined the bot)

apply_time_zone()

Applies the timezone of the bot to a date and time.

Argument 1: The date and time to adjust to the timezone.

Example:

{apply_time_zone("01-03-2024 00:07:48.030700")} ➡️ "01-03-2024 02:07:48.030700" (assuming the bot's timezone is +2)

time_passed()

Calculates the time elapsed from a given date to the current time, according to the UTC timezone.

Argument 1: The date from which to calculate the elapsed time.

Argument 2 (optional): The unit of measurement of the elapsed time to obtain. By default, it is 'seconds', but it can also be 'minutes', 'hours', or 'days'.
Other measurement forms

minutes: minute, m

seconds: second, s

hours: hour, h

days: day, d

Example:

{time_passed("25-02-2024", "days")} ➡️ 1.02588 (assuming today is 26-02-2014)

time_left()

Calculates the time remaining until a given date from the current time, according to the UTC timezone.

Argument 1: The date until which to calculate the remaining time.

Argument 2 (optional): The unit of measurement of the remaining time to obtain. By default, it is 'seconds', but it can also be 'minutes', 'hours', or 'days'.
Other measurement forms

minutes: minute, m

seconds: second, s

hours: hour, h

days: day, d

Example:

{time_left("02-03-2024", "days")} ➡️ 0.97458 (assuming today is 01-03-2014)

time_add()

This function adds a specific amount of time to a given date and returns it.

Argument 1: The date to which you want to add time.

Argument 2: The amount of time you want to add, must be a floating-point number.

Argument 3: The unit of time to add. By default, it is 'seconds', but it can also be 'minutes', 'hours', or 'days'.
Other measurement forms

minutes: minute, m

seconds: second, s

hours: hour, h

days: day, d

Example:

{time_add("01-03-2024 00:07:48.030700", 30, "days")} ➡️ "31-03-2024 00:07:48.030700"

time_diff()

Calculates the time difference between two given dates.

Argument 1: The first date and time.

Argument 2: The second date and time.

Argument 3: The unit of time in which you want to express the time difference. By default, it is 'seconds', but it can also be 'minutes', 'hours', or 'days'.
Other measurement forms

minutes: minute, m

seconds: second, s

hours: hour, h

days: day, d

Examples:

{time_diff("01-03-2024", "02-03-2024", "days")} ➡️ 1

{time_diff("02-03-2024", "01-03-2024", "days")} ➡️ -1

progress_bar()

Generates a visual progress bar based on a given percentage.

Argument 1: The percentage of completion progress. It must be a numeric value between 0 and 100.

Argument 2: The total length of the progress bar. It must be a positive integer representing the number of blocks that make up the bar.

Argument 3 (optional): The character representing completed blocks in the progress bar. By default, it's "🟩".

Argument 4 (optional): The character representing pending blocks in the progress bar. By default, it's "⬜".

Examples:

{progress_bar(30, 10)} ➡️ 🟩🟩🟩⬜️⬜️⬜️⬜️⬜️⬜️⬜️

{progress_bar(60, 10, "*", "-")} ➡️ ******----

urlencode()

This function takes a string and encodes special characters according to URL rules.

Argument 1: The string to encode.

Argument 2 (optional): A string of characters that are considered safe and will not be encoded. By default, it includes the characters ":/&=?".

Example:

{urlencode("https://www.example.com/search?q=visualmaker bot creator")} ➡️ "https://www.example.com/search?q=visualmaker%20bot%20creator"

urldecode()

This function takes a URL-encoded string and decodes it according to URL rules.

Argument 1: The URL-encoded string to decode.

Argument 2 (optional): The encoding scheme used to decode the string. By default, it's 'utf-8'.

Example:

{urlencode("https://www.example.com/search?q=visualmaker%20bot%20creator")} ➡️ "https://www.example.com/search?q=visualmaker bot creator"

loop()

Use this function to represent cursors like ref_list (list of user referrals) and bot_top_ref (list of users with most referrals in the bot), and other data, in the desired format. This function consumes 3 executions with its use.

Argument 1: `data`, the cursor or data you want to represent.

Argument 2: `text`, a text string in the desired format for representation.

Argument 3 (optional): `page`, an integer indicating the page from which to start. By default, it's 0 (the first page).

Argument 4 (optional): `max_per_page`, an integer indicating the maximum elements to represent per page. By default, it's 10 for cursors and 50 for other data types.

Argument 5 (optional): `values`, a tuple of text strings to enhance the representation of the text.
Information

You can access details of each user or item through item.<primitive_variable>, see primitive variables here.

What you see in the examples as \n means new line, it's for displaying the next user below.

Examples:

{loop(ref_list, '{item.first_name}\n', page=0)}: Returns a list showing the first name of the last 10 referrals of the user who executed the function, one below the other, starting from the first page.

{loop(ref_list, '{item.first_name}\n', page=1)}: Returns a list showing the first name of the last 10 referrals of the user who executed the function, one below the other, but this time it's the second page.

{loop(ref_list, '@{item.username}\n', max_per_page=3)}: Returns a list showing the username of the last 3 referrals of the user who executed the function, one below the other.

{loop(bot_top_ref, '{} {item.first_name} ({item.id})\n', max_per_page=3, values=('1️⃣', '2️⃣', '3️⃣'))}: Returns a list showing the name and ID (in parentheses) of the top 3 users with the most referrals in the bot. Additionally, it's formatted to give a more appealing look, it will display something like...

1️⃣ John (1234567)

2️⃣ Mary (2345678)

3️⃣ Pedro (3456789)

filter()

This function filters the elements of a list or dictionary based on a specified condition.

Argument 1: The condition to be evaluated for each element of the iterable. The condition must be a text string.

Argument 2: The list or dictionary from which to filter the elements. If it's a dictionary, the values of the dictionary will be used for condition evaluation.

Examples:

{filter('x > 5', [3, 7, 2, 9, 6, 1, 8])} ➡️ [7, 9, 6, 8]: Returns a list with elements greater than 5.

{filter("x % 2 == 0", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])} ➡️ [2, 4, 6, 8, 10]: Returns a list with all even numbers.

{filter('len(x) > 5', ['apple', 'banana', 'orange', 'strawberry', 'grape'])} ➡️ ['banana', 'orange', 'strawberry']: Returns a list with elements having more than 5 characters.

{filter('x.age > 25', {'Alice': {'age': 30, 'gender': 'F'}, 'Bob': {'age': 22, 'gender': 'M'}, 'Charlie': {'age': 35, 'gender': 'M'}})} ➡️ [{'age': 30, 'gender': 'F'}, {'age': 35, 'gender': 'M'}]: Filters a dictionary of people to get those who are older than 25.

{filter('x.status == True', {'123': {'name': 'John', 'status': True}, '456': {'name': 'Mary', 'status': False}, '789': {'name': 'Pedro', 'status': True}})} ➡️ [{'name': 'John', 'status': True}, {'name': 'Pedro', 'status': True}]: Returns a list with all dictionaries that have status as True.

reduce()

This function reduces the elements of a list or dictionary to a single value based on a specific condition.

Argument 1: The condition that defines how the iterable will be reduced. The condition must be a text string.

Argument 2: The list or dictionary to be reduced.

Examples:

{reduce('x + y', [1, 2, 3, 4, 5])} ➡️ 15: Returns the sum of all

elements in the list.

{reduce('x + y', ['hello', ' ', 'world', '!'])} ➡️ "hello world!": Reduces a list of strings to their concatenation.

{reduce('max(x, y)', {'Alice': 25, 'Bob': 35, 'Charlie': 30})} ➡️ 35: 35 is the maximum age.

{reduce('condition(x.status == True, x, y)', {'123': {'name': 'John', 'status': False}, '456': {'name': 'Mary', 'status': True}})} ➡️ {'name': 'Mary', 'status': True}: Returns the dictionary that has status as True.