What are functions?¶
Functions allow you to perform more advanced operations within expressions. They are written in the following way:
function(argument1, argument2)
Arguments are the data you pass to the function for it to do its work, they are enclosed in parentheses and separated by commas.
All the functions of VisualMaker¶
min()¶
Returns the smallest number from the provided arguments.
Arguments: numbers (no limit).
Examples:
{min(5, 7, 2, 6.1, 3)}➡️2(the smallest number)
{min(-5, -10, 3, 0)}➡️-10(the smallest considering negative numbers)
"The lowest value is {min(10, 20, 30)}"➡️"The lowest value is 10"
max()¶
Returns the largest number from the provided arguments.
Arguments: numbers (no limit).
Examples:
{max(5, 7, 2, 6.1, 3)}➡️7(the largest number)
{max(100, 50, 75)}➡️100
"The largest number is {max(3.5, 8.2, 6.8)}"➡️"The largest number is 8.2"
round()¶
Rounds a number to the nearest integer or to a specific number of decimals.
Argument 1: number to round.
Argument 2: (optional) the number of decimals the rounded number should have.
Examples:
{round(12.8649)}➡️13(rounds to the nearest integer)
{round(12.8649, 2)}➡️12.86(rounds to 2 decimals)
{round(0.44444, 3)}➡️0.444(rounds to 3 decimals)
"The approximate value is {round(7.5678, 1)}"➡️"The approximate value is 7.6"
ceil()¶
Rounds a number up to the nearest integer.
Argument 1: number.
Examples:
{ceil(8.5649)}➡️9
{ceil(-3.4)}➡️-3(the nearest integer rounded up for negative numbers)
"The rounded-up number is {ceil(4.1)}"➡️"The rounded-up number is 5"
floor()¶
Rounds a number down to the nearest integer.
Argument 1: number.
Examples:
{floor(8.5649)}➡️8
{floor(-3.4)}➡️-4(the nearest integer rounded down for negative numbers)
"The rounded-down number is {floor(9.9)}"➡️"The rounded-down number is 9"
random()¶
Generates a random number between two values. If one of the arguments has more decimals, the result will respect them.
Argument 1: minimum value.
Argument 2: maximum value.
Examples:
{random(1, 10)}➡️3(random between 1 and 10)
{random(1.001, 2)}➡️1.329(random between 1.001 and 2, the result will have 3 decimals)
"The random number is {random(100, 200)}"➡️"The random number is 152"
absolute()¶
Returns the absolute value of a number (removes the negative sign).
Argument 1: number.
Examples:
{absolute(-5)}➡️5
{absolute(10)}➡️10
"The absolute value of -3 is {absolute(-3)}"➡️"The absolute value of -3 is 3"
pick_one()¶
Selects a random element from the provided arguments.
Argument 1: any data type (no limit).
Examples:
{pick_one(5, "text", True, 16)}➡️"text"(randomly selected)
{pick_one("red", "green", "blue")}➡️"green"
"The chosen color is {pick_one("red", "yellow", "blue")}"➡️"The chosen color is blue"
pick_by_index()¶
Selects an element from a list, tuple, or string by its position (index).
Argument 1: List, tuple, or string.
Argument 2: Index (starting from 0).
Examples:
{pick_by_index(("John", "Mary", 10), 0)}➡️"John"(selected index0, it's the first)
{pick_by_index(["John", "Mary", 10], 1)}➡️"Mary"(selected index1, it's the second)
{pick_by_index("text", 3)}➡️"t"(selected index3from the text, it's the 4th character)
"The third element in the list is {pick_by_index([5, 10, 15], 2)}"➡️"The third element in the list is 15"
Note on indices
Indices always start from 0. For example:
- In
("a", "b", "c"), index0is"a",1is"b", and2is"c"
startswith()¶
Returns True if a text starts with a specific substring, otherwise returns False.
Argument 1: Main text.
Argument 2: Substring to check.
Examples:
{startswith("this is a string", "this")}➡️True(the text starts with"this")
{startswith("my bot", "the")}➡️False
endswith()¶
Returns True if a text ends with a specific substring, otherwise returns False.
Argument 1: Main text.
Argument 2: Substring to check.
Examples:
{endswith("this is a string", "ing")}➡️True(the text ends with"ing")
{endswith("my bot", "bot")}➡️True
capitalize()¶
Converts the first letter of the text to uppercase and the rest to lowercase.
Argument 1: Text to capitalize.
Examples:
{capitalize("john")}➡️"John"
{capitalize("HELLO")}➡️"Hello"
"Capitalized text: {capitalize('text to modify')}"➡️"Capitalized text: Text to modify"
capitalize_all()¶
Converts the first letter of each word to uppercase.
Argument 1: Text to capitalize.
Example:
{capitalize_all("my name is jjohn")}➡️"My Name Is John"
{capitalize_all("learning expressions")}➡️"Learning Expressions"
"Fully capitalized text: {capitalize_all('hello from telegram')}"➡️"Fully capitalized text: Hello From Telegram"
len()¶
Returns the length of a string, list, or tuple.
Argument 1: Text, list, or tuple.
Examples:
{len("this is a string")}➡️16(it has a length of 16 characters)
{len(["red", "green", "blue"])}➡️3(the list has 3 elements)
{len(("a", "b", "c", "d"))}➡️4(the tuple has 4 elements)
"The length of the text is: {len('VisualMaker')}"➡️"The length of the text is: 11"
replace()¶
Replaces all occurrences of a text within another.
Argument 1: Text to replace.
Argument 2: New text.
Argument 3: Main text.
Examples:
{replace("sunny", "rainy", "Today is a sunny day.")}➡️"Today is a rainy day."
{replace("dog", "cat", "My dog is adorable.")}➡️"My cat is adorable."
"Modified phrase: {replace('tomorrow', 'today', 'tomorrow will be another day')}"➡️"Modified phrase: today will be another day"
slice()¶
Slices a string, returning a specific portion.
Argument 1: Main text.
Argument 2: Start index (optional, if omitted starts from the beginning).
Argument 3: End index (optional, if omitted ends at the last character).
Examples:
{slice("Hello World", 3, 7)}➡️"lo Wo"
{slice("VisualMaker is amazing", 12)}➡️"is amazing"(from index 12 to the end)
"Extracted portion: {slice('Cutting text', 3, 7)}"➡️"Extracted portion: ting"
is_inside()¶
Returns True if an element is inside a list, tuple, or text, otherwise returns False.
Argument 1: Element to search for.
Argument 2: List, tuple, or text.
Examples:
{is_inside("John", ("John", "Mary", 10))}➡️True("John"is in the tuple)
{is_inside("Pablo", ["John", "Mary", 10])}➡️False("Pablo"is not in the list)
{is_inside("ex", "text")}➡️True("ex"is in"text")
is_string()¶
Returns True if the argument is a string, otherwise returns False.
Argument 1: Element to check.
Examples:
{is_string("hello")}➡️True
{is_string(123)}➡️False
{is_string(True)}➡️False
is_numeric()¶
Returns True if the argument is numeric, otherwise returns False.
Argument 1: Element to check.
Examples:
{is_numeric(123)}➡️True
{is_numeric("3.14")}➡️True
{is_numeric("hello")}➡️False
is_bool()¶
Returns True if the argument is a boolean (True or False), otherwise returns False.
Argument 1: Object to check.
Examples:
{is_bool(True)}➡️True
{is_bool(False)}➡️True
{is_bool("False")}➡️False("False"is a string, not a boolean)
to_string()¶
Converts an object into its string representation.
Argument 1: Object to convert.
Examples:
{to_string(123)}➡️"123"
{to_string(True)}➡️"True"
to_number()¶
Converts an object into a floating-point number.
Argument 1: Object to convert.
Example:
{to_number("3.14")}➡️3.14
to_integer()¶
Converts an object into an integer.
Argument 1: Object to convert.
Examples:
{to_integer(3.14)}➡️3
{to_integer("10")}➡️10
to_upper()¶
Converts a text to uppercase.
Argument 1: Text to convert.
Example:
{to_upper("hello visualmaker")}➡️"HELLO VISUALMAKER"
to_lower()¶
Converts a text to lowercase.
Argument 1: Text to convert.
Example:
{to_lower("HELLO VISUALMAKER")}➡️"hello visualmaker"
fix()¶
Adjusts the number of decimals of a number. Removes trailing zeros. Returns as a number.
Argument 1: Number to adjust, can be a string representing a number.
Argument 2: Desired number of decimals.
Examples:
{fix(3.141592653589793, 2)}➡️3.14
{fix(10.124054, 4)}➡️10.124
{fix("42.50000", 1)}➡️42.5
hardfix()¶
Adjusts the number of decimals of a number. Keeps the trailing zeros. Returns as a string.
Argument 1: Number to adjust, can be a string representing a number.
Argument 2: Desired number of decimals.
Examples:
{hardfix(10.124054, 4)}➡️"10.1240"
{hardfix(8.31, 8)}➡️"8.31000000"
{hardfix("42", 2)}➡️"42.00"
count()¶
Counts the occurrences of a substring within a string.
Argument 1: Main text.
Argument 2: Substring to count.
Examples:
{count("hello world", "o")}➡️2(oappears 2 times)
{count("abababab", "ab")}➡️4(abappears 4 times)
{count("this is an example", "is")}➡️2
find()¶
Returns the position of the first occurrence of a substring within a text. If not found, it returns None.
Argument 1: Main text.
Argument 2: Substring to search for.
Example:
{find("hello world", "world")}➡️6
{find("Visual Maker", "X")}➡️None
condition()¶
Evaluates a condition and returns a value based on whether it is true (True) or false (False).
Argument 1: Condition to evaluate.
Argument 2: Value if true.
Argument 3: Value if false.
Examples:
{condition(5 > 3, "True", "False")}➡️"True"
{condition(2 == 7, "Is true", "Is false")}➡️"Is false"
{condition(is_numeric(3.14), "Is number", "Not a number")}➡️"Is number"
"Is 15 greater than 10? {condition(15 > 10, 'Yes', 'No')}"➡️"Is 15 it greater than 10? Yes"
date_now()¶
Returns the current date and time in UTC time zone. No arguments are required.
Example:
{date_now()}➡️"01-03-2024 00:07:48"
date_now_tz()¶
Returns the current date and time according to the configured time zone. No arguments are required.
Example:
{date_now_tz()}➡️"01-03-2024 03:08:28"
apply_tz()¶
Applies the bot's time zone to a given date and time.
Argument 1: Date and time.
Examples:
{apply_tz("01-03-2024 00:07:48")}➡️"01-03-2024 02:07:48"(assuming the bot's time zone is +2)
date_format()¶
Formats a date and time in a specific format.
Argument 1: Date and time to format.
Argument 2: Desired format (default: "%d-%m-%Y %H:%M:%S").
Meanings
%d: Day of the month (01-31).
%m: Month of the year (01-12).
%Y (uppercase): Year (4 digits).
%y (lowercase): Year (2 digits).
%H (uppercase): Time in 24-hour format (00-23).
%h (lowercase): Time in 12-hour format (01-12).
%M: Minutes (00-59).
%S: Seconds (00-59).
%p: Show period (AM and PM).
Examples:
{date_format("01-03-2024 00:07:48", "%d/%m/%Y")}➡️"01/03/2024"
{date_format("01-03-2024 00:07:48", "%h:%M %p")}➡️"12:07 AM"
{date_format(date_joined, "%m-%y")}➡️"03-24"(based on the date when the user joined the bot)
time_passed()¶
Calculates the time elapsed from a date to the current moment in a specific unit, according to UTC time.
Argument 1: Start date.
Argument 2: (optional) Time unit (default: 'seconds', but can also be 'minutes', 'hours', or 'days').
Other units of measurement
minutes: minute, m
seconds: second, s
hours: hour, h
days: day, d
Example:
{time_passed("29-02-2024", "days")}➡️1.02588(assuming today is 01-03-2024)
time_left()¶
Calculates the remaining time until a specific date from the current moment in a specific unit, according to UTC time.
Argument 1: End date.
Argument 2: (optional) Time unit (default: 'seconds', but can also be 'minutes', 'hours', or 'days').
Other units of measurement
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-2024)
time_add()¶
Adds a specific amount of time to a given date.
Argument 1: Initial date (string in `dd-mm-yyyy hh:mm:ss` format).
Argument 2: Amount of time to add (floating-point number).
Argument 3: (optional) Time unit (default: 'seconds', but can also be 'minutes', 'hours', or 'days').
Other units of measurement
minutes: minute, m
seconds: second, s
hours: hour, h
days: day, d
Examples:
{time_add("01-03-2024 00:07:48", 30, "days")}➡️"31-03-2024 00:07:48"
{time_add("01-03-2024 10:00:00", 2, "hours")}➡️"01-03-2024 12:00:00"
{time_add("01-03-2024 00:00:00", 90, "minutes")}➡️"01-03-2024 01:30:00"
"In 15 seconds it will be: {time_add(date_now(), 15, 's')}"
time_diff()¶
Calculates the difference between two dates and expresses it in a specific unit.
Argument 1: First date (string in `dd-mm-yyyy hh:mm:ss` format).
Argument 2: Second date (string in `dd-mm-yyyy hh:mm:ss` format).
Argument 3: Time unit (`seconds`, `minutes`, `hours`, `days`).
Other units of measurement
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: Percentage completed (a number between 0 and 100).
Argument 2: Total length of the bar (positive integer).
Argument 3: (optional) Character for completed blocks (default: `🟩`).
Argument 4: (optional) Character for pending blocks (default: `⬜`).
Examples:
{progress_bar(30, 10)}➡️🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜
{progress_bar(60, 10, "*", "-")}➡️******----
urlencode()¶
Encodes special characters in a string according to URL rules.
Argument 1: String to encode.
Argument 2: (optional) Characters considered safe (default: `":/&=?"`).
Example:
{urlencode("https://www.example.com/search?q=visualmaker bot creator")}➡️"https://www.example.com/search?q=visualmaker%20bot%20creator"
{urlencode("Hello World")}➡️"Hello%20World"
urldecode()¶
Decodes a URL-encoded string.
Argument 1: Encoded string.
Argument 2: (optional) Encoding scheme (default: `utf-8`).
Example:
{urldecode("https://www.example.com/search?q=visualmaker%20bot%20creator")}➡️"https://www.example.com/search?q=visualmaker bot creator"
{urldecode("Hello%20World")}➡️"Hello World"
loop()¶
Represents cursors like ref_list (list of referrals of a user) and bot_top_ref (list of users with the most referrals of the bot), and other data, in the desired format, with pagination options. This function consumes 3 executions when used.
Argument 1: data, the cursor or the data to be represented.
Argument 2: text, a string representing the desired format for the representation.
Argument 3: (optional) page, an integer indicating the page to start from (default: `0`, the first page).
Argument 4: (optional) max_per_page, an integer indicating the maximum number of elements to represent per page. (default: `10` for cursors and `50` for other types of data).
Argument 5: (optional) values, a tuple of strings to help enhance the text representation.
Info
You can access the details of each user or item through item.(native_variable), see the native variables here.
What you will see in the examples as \n, means new line, to represent the next user below.
Examples:
{loop(ref_list, '{item.first_name}\n', page=0)}: A string with the names of the first 10 referrals, starting from the first page.
{loop(ref_list, '{item.first_name}\n', page=1)}: A string with the names of the first 10 referrals, starting from the second page.
{loop(ref_list, '@{item.username}\n', max_per_page=3)}: A string with the first 3 referred users of the user who ran the function.
{loop(bot_top_ref, '{} {item.first_name} ({item.id}) - {item.ref_count} refs\n', max_per_page=3, values=('1️⃣', '2️⃣', '3️⃣'))}: A string with the names and IDs (in parentheses) of the top 3 users with the most referrals, formatted to look more attractive, displaying something like the following:1️⃣ John (1234567) - 85 refs
2️⃣ Mary (2345678) - 62 refs
3️⃣ Pedro (3456789) - 41 refs
filter()¶
Filters elements from a list or dictionary based on a condition.
Argument 1: Condition (string).
Argument 2: List or dictionary.
Examples:
{filter('x > 5', [3, 7, 2, 9, 6, 1, 8])}➡️[7, 9, 6, 8]: Returns a list of 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 of all even numbers.
{filter('len(x) > 5', ['apple', 'banana', 'orange', 'strawberry', 'grape'])}➡️['banana', 'orange', 'strawberry']: Returns a list of items with more than 5 characters.
{filter('x.age > 25', {'Alice': {'age': 30, 'genre': 'F'}, 'Bob': {'age': 22, 'genre': 'M'}, 'Charlie': {'age': 35, 'genre': 'M'}})}➡️[{'age': 30, 'genre': 'F'}, {'age': 35, 'genre': 'M'}]: Filters a dictionary of people to get those over 25 years old.
{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 of all dictionaries wherestatusisTrue.
reduce()¶
Reduces the elements of a list or dictionary to a single value based on a condition.
Argument 1: Condition (string).
Argument 2: List or dictionary to reduce.
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: Finds 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 withstatusasTrue.