Module tools
format a number with comma-separated thousands.
Functions
| commands(username, command_table) | create a new commands builder for matching bot commands. |
| create_link(text, link, parse_mode) | create a formatted hyperlink for the given parse mode. |
| download_file(url, name, path) | download a file from a URL and save it to disk. |
| escape_bash(str) | escape a string for safe use in a bash single-quoted context. |
| escape_html(str) | escape special HTML characters (&, <, >) in a string. |
| escape_markdown(str) | escape special markdown characters in a string (v1 markdown). |
| escape_markdown_v2(str) | escape special MarkdownV2 characters in a string. |
| file_exists(path) | check whether a file exists at the given path. |
| format_ms(milliseconds) | format milliseconds into HH:MM:SS string. |
| format_time(seconds) | format seconds into a human-readable time string (e.g. |
| get_file_as_table(path) | read a file and return its lines as a table. |
| get_formatted_user(user_id, name, parse_mode) | format a user mention link with the given parse mode. |
| get_linked_name(id) | get an HTML-formatted linked name for a user by their ID. |
| get_word(str, i) | get the i-th whitespace-delimited word from a string. |
| input(s) | extract the text after the first space in a string (i.e. |
| json_to_table(path) | read a JSON file and decode it into a lua table. |
| pretty_print(tbl) | encode a table as a pretty-printed JSON string. |
| random_string(length, amount) | generate one or more random alphanumeric strings of a given length. |
| read_file(path) | read the entire contents of a file as a string. |
| round(num, idp) | round a number to the specified number of decimal places. |
| save_to_file(data, filename, append) | save data to a file in /tmp/. |
| table_size(t) | count the number of entries in a table (including non-sequential keys). |
| tools.commands_meta:command(command) | add a command pattern to the commands table, including variants with and without bot username. |
| trim(str) | strip leading and trailing whitespace from a string. |
| utf8_len(str) | count the number of UTF-8 characters in a string. |
Functions
- commands(username, command_table)
-
create a new commands builder for matching bot commands.
Parameters:
- username string the bot username used in command patterns
- command_table table optional existing table to append patterns to
Returns:
-
table a commands builder with a :command() method for chaining
- create_link(text, link, parse_mode)
-
create a formatted hyperlink for the given parse mode.
supports markdown, markdownv2, and HTML (default).
Parameters:
- text string the display text
- link string the URL to link to
- parse_mode string|boolean the parse mode ('markdown', 'markdownv2', or HTML by default; true means 'markdown')
Returns:
-
string the formatted link string
- download_file(url, name, path)
-
download a file from a URL and save it to disk.
Parameters:
- url string the URL to download from
- name string optional filename (defaults to timestamp with extension from URL)
- path string optional directory path to save to (defaults to /tmp/)
Returns:
- string|boolean the full file path on success, or false on failure
- number|string the HTTP status code or error message on failure
- escape_bash(str)
-
escape a string for safe use in a bash single-quoted context.
Parameters:
- str string the string to escape
Returns:
-
string the escaped string wrapped in single quotes
- escape_html(str)
-
escape special HTML characters (&, <, >) in a string.
Parameters:
- str string the string to escape
Returns:
-
string the escaped string
- escape_markdown(str)
-
escape special markdown characters in a string (v1 markdown).
Parameters:
- str string the string to escape
Returns:
-
string the escaped string
- escape_markdown_v2(str)
-
escape special MarkdownV2 characters in a string.
Parameters:
- str string the string to escape
Returns:
-
string the escaped string
- file_exists(path)
-
check whether a file exists at the given path.
Parameters:
- path string the file path to check
Returns:
-
boolean true if the file exists, false otherwise
- format_ms(milliseconds)
-
format milliseconds into HH:MM:SS string.
Parameters:
- milliseconds number the duration in milliseconds
Returns:
-
string the formatted time string in HH:MM:SS format
- format_time(seconds)
-
format seconds into a human-readable time string (e.g. "5 minutes", "2 hours").
returns the largest appropriate time unit.
Parameters:
- seconds number the duration in seconds
Returns:
-
string|boolean the formatted time string, or false if input is invalid
- get_file_as_table(path)
-
read a file and return its lines as a table.
Parameters:
- path string the file path to read
Returns:
-
table a sequential table of lines (empty table if file not found)
- get_formatted_user(user_id, name, parse_mode)
-
format a user mention link with the given parse mode.
generates a tg://user?id= deep link for mentioning users by ID.
Parameters:
- user_id number the user's ID
- name string the display name
- parse_mode string the parse mode ('html', 'markdownv2', or markdown; defaults to 'MarkdownV2')
Returns:
-
string|boolean the formatted user mention string, or false if missing params
- get_linked_name(id)
-
get an HTML-formatted linked name for a user by their ID.
fetches the user's chat info and returns their first name as an HTML link if they have a username.
Parameters:
- id number the user or chat ID
Returns:
-
string|boolean the HTML-formatted name, or false on failure
- get_word(str, i)
-
get the i-th whitespace-delimited word from a string.
Parameters:
- str string the input string
- i number optional word index (defaults to 1)
Returns:
-
string|boolean the matched word, or false if not found
- input(s)
-
extract the text after the first space in a string (i.e. command input).
Parameters:
- s string the input string
Returns:
-
string|boolean the text after the first space, or false if none
- json_to_table(path)
-
read a JSON file and decode it into a lua table.
Parameters:
- path string the file path to the JSON file
Returns:
-
table the decoded table (empty table if file not found or invalid)
- pretty_print(tbl)
-
encode a table as a pretty-printed JSON string.
Parameters:
- tbl table the table to encode
Returns:
-
string the indented JSON string
- random_string(length, amount)
-
generate one or more random alphanumeric strings of a given length.
Parameters:
- length number the length of each random string
- amount number optional number of strings to generate
Returns:
-
string|table a single string if amount is nil, or a table of strings
- read_file(path)
-
read the entire contents of a file as a string.
Parameters:
- path string the file path to read
Returns:
-
string|boolean the file contents, or false on failure
- round(num, idp)
-
round a number to the specified number of decimal places.
Parameters:
- num number the number to round
- idp number optional number of decimal places (defaults to 0)
Returns:
-
number the rounded number
- save_to_file(data, filename, append)
-
save data to a file in /tmp/.
Parameters:
- data string the data to write
- filename string the filename to write to (saved under /tmp/)
- append boolean optional flag to append instead of overwrite
Returns:
-
string|boolean the full file path on success, or false on failure
- table_size(t)
-
count the number of entries in a table (including non-sequential keys).
Parameters:
- t table the table to count
Returns:
-
number the number of key-value pairs
- tools.commands_meta:command(command)
-
add a command pattern to the commands table, including variants with and without bot username.
Parameters:
- command string the command name (without prefix)
Returns:
-
table self for method chaining
- trim(str)
-
strip leading and trailing whitespace from a string.
Parameters:
- str string the string to trim
Returns:
-
string the trimmed string
- utf8_len(str)
-
count the number of UTF-8 characters in a string.
Parameters:
- str string the string to measure
Returns:
-
number the number of UTF-8 characters