Block Module

TagScriptEngine.block.implicit_bool(string: str) → bool | None[source]

Parse a string to a boolean.

>>> implicit_bool("true")
True
>>> implicit_bool("FALSE")
False
>>> implicit_bool("abc")
None

Parameters:

string (str) – The string to convert.

Returns:

bool – The boolean value of the string.
None – The string failed to parse.

TagScriptEngine.block.helper_parse_if(string: str) → bool | None[source]

Parse an expression string to a boolean.

>>> helper_parse_if("this == this")
True
>>> helper_parse_if("2>3")
False
>>> helper_parse_if("40 >= 40")
True
>>> helper_parse_if("False")
False
>>> helper_parse_if("1")
None

Parameters:

string (str) – The string to convert.

Returns:

bool – The boolean value of the expression.
None – The expression failed to parse.

TagScriptEngine.block.helper_split(split_string: str, easy: bool = True, *, maxsplit: int | None = None, double_semicolon: bool = False) → List[str] | None[source]

A helper method to universalize the splitting logic used in multiple blocks and adapters. Please use this wherever a verb needs content to be chopped at | or ~. Embed parsing can also opt into ;; taking priority over the other delimiters.

>>> helper_split("this, should|work")
["this, should", "work"]

class TagScriptEngine.block.AllowedMentionsBlock(*args, **kwargs)[source]

Bases: Block

The {allowedmentions} block attempts to enable mentioning of roles. Passing no parameter enables mentioning of all roles within the message content. However passing a role name or ID to the block parameter allows mentioning of that specific role only. Multiple role name or IDs can be included, separated by a comma “,”. By default, mentioning is only triggered if the execution author has “manage server” permissions. However, using the “override” keyword as a payload allows mentioning to be triggered by anyone.

Usage: {allowedmentions(<role, None>):["override", None]}

Aliases: mentions

Payload: “override”, None

Parameter: role, None

Examples:

{allowedmentions}
{allowedmentions:override}
{allowedmentions(@Admin, Moderator):override}
{allowedmentions(763522431151112265, 812949167190048769)}
{mentions(763522431151112265, 812949167190048769):override}

classmethod will_accept(ctx: Context) → bool[source]

Describes whether the block is valid for the given Context.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: Whether the block should be processed for this Context.
Return type:: bool

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.AllBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The all block checks that all of the passed expressions are true. Multiple expressions can be passed to the parameter by splitting them with |.

The payload is a required message that must be split by |. If the expression evaluates true, then the message before the | is returned, else the message after is returned.

Usage: {all(<expression|expression|...>):<message>}

Aliases: and

Payload: message

Parameter: expression

Examples:

{all({args}>=100|{args}<=1000):You picked {args}.|You must provide a number between 100 and 1000.}
# if {args} is 52
You must provide a number between 100 and 1000.

# if {args} is 282
You picked 282.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.AnyBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The any block checks that any of the passed expressions are true. Multiple expressions can be passed to the parameter by splitting them with |.

The payload is a required message that must be split by |. If the expression evaluates true, then the message before the | is returned, else the message after is returned.

Usage: {any(<expression|expression|...>):<message>}

Aliases: or

Payload: message

Parameter: expression

Examples:

{any({args}==hi|{args}==hello|{args}==heyy):Hello {user}!|How rude.}
# if {args} is hi
Hello sravan#0001!

# if {args} is what's up!
How rude.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.AssignmentBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

Variables are useful for storing a value and referencing it later in a tag. Variables can be referenced using brackets as any other block.

Note

Variables are not parsed by default. You must use the parse method to parse a variable.
They are one of the most versatile and powerful features of TagScript.
By default, a tag cannot store data between invocations. This is where variables come in.
They are the only way to store data. And later retrieve it within the same invocation.

Usage: {=(<name>):<value>}

Aliases: assign, let, var

Payload: value

Parameter: name

Examples:

{=(message1):Hi there! How are you?}
{=(message2):It's a beautiful day today!}
{=(message3):Did you know that TagScript is a powerful tool?}

Now, call the variables by their names:
{message1} # Hi there! How are you?
{message2} # It's a beautiful day today!
{message3} # Did you know that TagScript is a powerful tool?

More example:
{=(prefix):!}
The prefix here is `{prefix}`.
# The prefix here is `!`.

{assign(day):Monday}
{if({day}==Wednesday):It's Wednesday my dudes!|The day is {day}.}
# The day is Monday.

Caution

You can name variables with anything except existing block names or aliases.
They will not reference the value in payload, if the name is same as an existing block name or alias.

Important

How Argument Parsing Works - In Detail

A variable is essentially a string that can be treated as a sequence of elements (words, numbers, etc.) when accessed. These elements are split using delimiters (spaces by default) and are indexed sequentially starting from 1.
A delimiter is a sequence of one or more characters that are used to split a string into a sequence of elements.
Once a variable is assigned, its value can be referenced and parsed (split and indexed) to extract specific parts. Let’s take a look at how it works.
Parsing out of bounds index will return the whole string.

Basic Argument Parsing

Example

“Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves”

So, our argument or args in short, would be:

{=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}

Note

args is just a variable name, perhaps the most common name, but you can name it anything.

Since, the default delimiter is space, so you can access the each element as follows:

{args(1)}  -> Coolaid
{args(2)}  -> is
{args(3)}  -> setting
{args(4)}  -> up
{args(5)}  -> the
{args(6)}  -> table.

{args(31)} -> Would return the whole string since it doesn't exist (indexing 31st element is out of bounds).

0 is special and returns the last element:

{args(0)}  -> gloves

Negative indices allow you to access elements from the end of the sequence:

{args(-1)}  -> work
{args(-2)}  -> of
{args(-3)}  -> pair
{args(-4)}  -> a
{args(-5)}  -> and
{args(-6)}  -> level,

Prefix Range Access (+n)

Prefixing an index with + returns all elements from the start up to and including that position:

{args(+3)}   -> Coolaid is setting
{args(+7)}   -> Coolaid is setting up the table. So,
{args(+13)}  -> Coolaid is setting up the table. So, he grabbed - a cordless drill,

Suffix Range Access (n+)

Suffixing an index with + returns all elements from that position (counting from the start) to the end:

{args(3+)}   -> setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
{args(7+)}   -> So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
{args(13+)}  -> drill, some screws, a spirit level, and a pair of work gloves

Negative Range Access (-n+)

Appending + to an negative-index returns a range — all elements from that position to the end:
Negative indices are first resolved from the end of the sequence, then range access continues forward to the end.

{args(-1+)}   -> work gloves # Since {args(0)} == gloves
{args(-11+)}  -> drill, some screws, a spirit level, and a pair of work gloves

Tip

+n → from start → n
n+ → from n → end (index resolved first)
-n → nth element from end
-n+ → nth element from end → then forward to end (index resolved first)

Advanced Argument Parsing

A custom delimiter can be passed as the payload to change how the value is split. The syntax is {variable(index):delimiter}:

# Using the same argument as before.
{=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}

1st Example:
{args(1):.}  -> Coolaid is setting up the table
{args(2):.}  -> So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves
{args(3):.}  -> Would return the entire string since there is no 3rd element.

2nd Example:
{args(1):-}  -> Coolaid is setting up the table. So, he grabbed
{args(2):-}  -> a cordless drill, some screws, a spirit level, and a pair of work gloves

Note

In the 1st example, the custom delimiter is ., hence the string is split by . leaving 2 elements.
In the 2nd example, the custom delimiter is -, hence the string is split by - leaving 2 elements.
Since in both the examples, there are 2 elements, so args(3) would return the entire string. Because the index 3rd element is out of bounds.

Nested Variables

Variables can be nested to perform multi-level parsing:

{=(raw):A - B, C, D}
{=(part):{raw(2):-}}

# "{raw(2):-}" splits "raw" by "-" and returns the 2nd element -> "B, C, D" (1st element is "A")
# Therefore, "part" == "B, C, D"

{part(1):,}  -> B
{part(2):,}  -> C

Another Example:
# What if you want to parse through the things that Coolaid grabbed?
# If you look closely the "-" delimiter is placed conveniently to separate the items. So, we'll use it:

{=(args):Coolaid is setting up the table. So, he grabbed - a cordless drill, some screws, a spirit level, and a pair of work gloves}
{=(items):{args(2):-}}

# "{args(2):-}" splits "args" by "-" and returns the 2nd element -> "a cordless drill, ... and a pair of work gloves"
# Therefore, "items" == "a cordless drill, some screws, a spirit level, and a pair of work gloves"

Items:
{items(1):,}  -> a cordless drill
{items(2):,}  -> some screws
{items(3):,}  -> a spirit level
{items(4):,}  -> and a pair of work gloves

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.BlacklistBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The blacklist block will attempt to convert the given parameter into a channel or role, using name or ID. If the user running the tag is in the targeted channel or has the targeted role, the tag will stop processing and it will send the response if one is given. Multiple role or channel requirements can be given, and should be split by a “,”.

Usage: {blacklist(<role,channel>):[response]}

Payload: response, None

Parameter: role, channel

Examples:

{blacklist(Muted)}
{blacklist(#support):This tag is not allowed in #support.}
{blacklist(Tag Blacklist, 668713062186090506):You are blacklisted from using tags.}

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.BreakBlock(*args, **kwargs)[source]

Bases: Block

The break block will force the tag output to only be the payload of this block, if the passed expresssion evaluates true. If no message is provided to the payload, the tag output will be empty.

This differs from the StopBlock as the stop block stops all tagscript processing and returns its message while the break block continues to process blocks. If command blocks exist after the break block, they will still execute.

Usage: {break(<expression>):[message]}

Aliases: short, shortcircuit

Payload: message

Parameter: expression

Examples:

{break({args}==):You did not provide any input.}

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.SequentialGather(*awaitables: Awaitable[T])[source]

Bases: Awaitable[T]

Use this to run commands sequentially.

Parameters:: awaitables (Tuple[Awaitable[T]]) – the awaitables to be run sequentially.
Returns:: the result object.
Return type:: List[T]

class TagScriptEngine.block.CommandBlock(limit: int = 3)[source]

Bases: VerbRequiredBlock

Run a command as if the tag invoker had ran it. Only 3 command blocks can be used in a tag.

Usage: {command:<command>}

Aliases: c, com, command

Payload: command

Parameter: None

Examples:

{c:ping}
# invokes ping command

{c:ban {target(id)} Chatflood/spam}
# invokes ban command on the pinged user with the reason as "Chatflood/spam"

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.CooldownBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The cooldown block implements cooldowns when running a tag. The parameter requires 2 values to be passed: rate and per integers. The rate is the number of times the tag can be used every per seconds.

The payload requires a key value, which is the key used to store the cooldown. A key should be any string that is unique. If a channel’s ID is passed as a key, the tag’s cooldown will be enforced on that channel. Running the tag in a separate channel would have a different cooldown with the same rate and per values.

The payload also has an optional message value, which is the message to be sent when the cooldown is exceeded. If no message is passed, the default message will be sent instead. The cooldown message supports 2 blocks: key and retry_after.

Note

Delimiter for the parameter (<rate> and <per>): | or ~. Where | takes priority over ~.

Usage: {cooldown(<rate>|<per>):<key>|[message]}

Payload: key, message

Parameter: rate, per

Examples:

{cooldown(1|10):{author(id)}}
# the tag author used the tag more than once in 10 seconds
# The bucket for 741074175875088424 has reached its cooldown. Retry in 3.25 seconds."

{cooldown(3|3):{channel(id)}|Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **{retry_after}** seconds."}
# the tag was used more than 3 times in 3 seconds in a channel
# Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **0.74** seconds.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.EmbedBlock(*args, **kwargs)[source]

Bases: Block

An embed block will send an embed in the tag response. There are two ways to use the embed block, either by using properly formatted embed JSON from an embed generator or manually inputting the accepted embed attributes.

JSON

Using JSON to create an embed offers complete embed customization. Multiple embed generators are available online to visualize and generate embed JSON.

Important

Embed Limits are:
- Title: 256 characters
- Description: 4096 characters
- Footer: 2048 characters
- Author: 256 characters
- Field name: 256 characters
- Field value: 1024 characters
The total length of the embed must not exceed 6000 characters.

Usage: {embed(<json>)}

Payload: None

Parameter: json

Examples:

Example 1:
{embed({"title":"Hello!", "description":"This is a test embed."})}

Example 2:
{embed({
    "title":"Here's a random duck!",
    "image":{"url":"https://random-d.uk/api/randomimg"},
    "color":15194415,
    "fields": [
        {
            "name": "Fun Fact",
            "value": "Ducks are birds that are well-adapted to life in and around water.",
            "inline": false
        }
    ]
})}

Manual

The following embed attributes can be set manually:

title
description
color
url
thumbnail
image
author
footer
field - (See below)

Adding a field to an embed requires the payload to be split by ;;, | or ~ into either 2 or 3 parts. The first part is the name of the field, the second is the text of the field, and the third optionally specifies whether the field should be inline.

Usage: {embed(<attribute>):<value>}

Payload: value

Parameter: attribute

Examples:

{embed(color):#37b2cb}
{embed(title):Rules}
{embed(description):Follow these rules to ensure a good experience in our server!}
{embed(field):Rule 1|Respect everyone you speak to.|false}
{embed(author):Mod Team|{author(avatar)}}
{embed(footer):Thanks for reading!|{guild(icon)}}

Both methods can be combined to create an embed in a tag. The following tagscript uses JSON to create an embed with fields and later set the embed title.

Caution

The JSON block acts as a base for the embed.
Since blocks are processed in order, the JSON block must come before any manual attribute blocks.
The manual attributes are used to modify or add to the embed created by the JSON block.

{embed({
    "description": "This is a test description.",
    "fields": [
        {
            "name": "Field 1",
            "value": "field description",
            "inline": false
        }
    ]
})}
{embed(title):My embed title}

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.FiftyFiftyBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The fifty-fifty block has a 50% change of returning the payload, and 50% chance of returning null.

Usage: {50:<message>}

Aliases: 5050, ?

Payload: message

Parameter: None

Examples:

I pick {if({5050:.}!=):heads|tails}
# I pick heads

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.IfBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The if block returns a message based on the passed expression to the parameter. An expression is represented by two values compared with an operator.

The payload is a required message that must be split by |. If the expression evaluates true, then the message before the | is returned, else the message after is returned.

Expression Operators:

Operator	Check	Example	Description
`==`	equality	a==a	value 1 is equal to value 2
`!=`	inequality	a!=b	value 1 is not equal to value 2
`>`	greater than	5>3	value 1 is greater than value 2
`<`	less than	4<8	value 1 is less than value 2
`>=`	greater than or equality	10>=10	value 1 is greater than or equal to value 2
`<=`	less than or equality	5<=6	value 1 is less than or equal to value 2

Usage: {if(<expression>):<message>]}

Payload: message

Parameter: expression

Examples:

{if({args}==63):You guessed it! The number I was thinking of was 63!|Too {if({args}<63):low|high}, try again.}
# if args is 63
# You guessed it! The number I was thinking of was 63!

# if args is 73
# Too low, try again.

# if args is 14
# Too high, try again.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.LooseVariableGetterBlock(*args, **kwargs)[source]

Bases: Block

The loose variable block represents the adapters for any seeded or defined variables. This variable implementation is considered “loose” since it checks whether the variable is valid during process(), rather than will_accept().

Usage: {<variable_name>([parameter]):[payload]}

Aliases: This block is valid for any inputted declaration.

Payload: Depends on the variable’s underlying adapter.

Parameter: Depends on the variable’s underlying adapter.

Examples:

{=(var):This is my variable.}
{var}
# This is my variable.

will_accept(ctx: Context) → bool[source]

Describes whether the block is valid for the given Context.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: Whether the block should be processed for this Context.
Return type:: bool

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.MathBlock(*args, **kwargs)[source]

Bases: Block

The math block performs mathematical calculations from the given payload expression.

Supports standard arithmetic operators, exponentiation, modulo, in-place operators, mathematical functions, and constants.

Supported Operators:

Operator	Description
`+`	Addition
`-`	Subtraction
`*`	Multiplication
`/`	Division
`^`	Exponentiation
`%`	Modulo
`+=`	In-place addition
`-=`	In-place subtraction
`*=`	In-place multiply
`/=`	In-place division

Supported Functions: sin, cos, tan, sinh, cosh, tanh, exp, abs, trunc, round, sgn, log (base 10), ln (natural), log2, sqrt

Constants: PI, E

Usage: {math:<expression>}

Aliases: m, +, calc

Payload: expression

Parameter: None

Examples:

{math:2+3}
# 5

{m:round(7/3)}
# 2

{calc:sin(PI/2)}
# 1.0

{+:7*6}
# 42

{m:sqrt(144)}
# 12.0

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.OverrideBlock(*args, **kwargs)[source]

Bases: Block

Override a command’s permission requirements. This can override mod, admin, or general user permission requirements when running commands with the Command Block. Passing no parameter will default to overriding all permissions.

In order to add a tag with the override block, the tag author must have Manage Server permissions.

This will not override bot owner commands or command checks.

Usage: {override(["admin"|"mod"|"permissions"]):[command]}

Payload: command

Parameter: “admin”, “mod”, “permissions”

Examples:

{override}
# overrides all commands and permissions

{override(admin)}
# overrides commands that require the admin role

{override(permissions)}
{override(mod)}
# overrides commands that require the mod role or have user permission requirements

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.PythonBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The in block serves three different purposes depending on the alias that is used.

The in alias checks if the parameter is anywhere in the payload.

The contains alias strictly checks if the parameter is in the payload, split by whitespace.

The index alias finds the location/index of the parameter in the payload, split by whitespace. If the parameter string is not found in the payload, it returns -1.

Note

Both contains and index perform exact matching on whitespace-split words. For example, food will not match food. (with trailing punctuation).

Usage: {in(<string>):<payload>}

Aliases: in, contains, index

Payload: payload

Parameter: string

Examples:

{in(apple pie):banana pie apple pie and other pie}
# true
{in(mute):How does it feel to be muted?}
# true
{in(a):How does it feel to be muted?}
# false

{contains(mute):How does it feel to be muted?}
# false
{contains(muted?):How does it feel to be muted?}
# true

{index(food):I love to eat food. everyone does.}
# -1 # because of the period. "food" != "food."
{index(food):I love to eat food everyone does}
# 4 # because "food" is the 4th word in the payload
{index(love):I love to eat food}
# 1 # because "love" is the 2nd word in the payload
{index(pie):I love to eat food}
# -1 # because "pie" is not in the payload

will_accept(ctx: Context) → bool[source]

Describes whether the block is valid for the given Context.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: Whether the block should be processed for this Context.
Return type:: bool

process(ctx: Context) → str[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.RandomBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

Pick a random item from a list of strings, split by either ~ or ,. An optional seed can be provided to the parameter to always choose the same item when using that seed.

Usage: {random([seed]):<list>}

Aliases: #, rand

Payload: list

Parameter: seed, None

Examples:

{random:Carl,Harold,Josh} attempts to pick the lock!
# Possible Outputs:
# Josh attempts to pick the lock!
# Carl attempts to pick the lock!
# Harold attempts to pick the lock!

{=(insults):You're so ugly that you went to the salon and it took 3 hours just to get an estimate.~I'll never forget the first time we met, although I'll keep trying.~You look like a before picture.}
{=(insult):{#:{insults}}}
{insult}
# Assigns a random insult to the insult variable

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.RangeBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The range block picks a random number from a range of numbers seperated by -. The number range is inclusive, so it can pick the starting/ending number as well. Using the rangef block will pick a number to the tenth decimal place.

An optional seed can be provided to the parameter to always choose the same item when using that seed.

Usage: {range([seed]):<lowest-highest>}

Aliases: rangef

Payload: number

Parameter: seed, None

Examples:

Your lucky number is {range:10-30}!
# Your lucky number is 14!
# Your lucky number is 25!

{=(height):{rangef:5-7}}
I am guessing your height is {height}ft.
# I am guessing your height is 5.3ft.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.RedirectBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

Redirects the tag response to either the given channel, the author’s DMs, or uses a reply based on what is passed to the parameter.

Usage: {redirect(<"dm"|"reply"|channel>)}

Payload: None

Parameter: “dm”, “reply”, channel

Examples:

{redirect(dm)}
{redirect(reply)}
{redirect(#general)}
{redirect(626861902521434160)}

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.ReplaceBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The replace block will replace specific characters in a string. The parameter should split by a ,, containing the characters to find before the command and the replacements after.

Usage: {replace(<original,new>):<message>}

Aliases: None

Payload: message

Parameter: original, new

Examples:

{replace(o,i):welcome to the server}
# welcime ti the server

{replace(1,6):{args}}
# if {args} is 1637812
# 6637862

{replace(, ):Test}
# T e s t

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.RequireBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The require block will attempt to convert the given parameter into a channel or role, using name or ID. If the user running the tag is not in the targeted channel or doesn’t have the targeted role, the tag will stop processing and it will send the response if one is given. Multiple role or channel requirements can be given, and should be split by a “,”.

Usage: {require(<role,channel>):[response]}

Aliases: whitelist

Payload: response, None

Parameter: role, channel

Examples:

{require(Moderator)}
{require(#general, #bot-cmds):This tag can only be run in #general and #bot-cmds.}
{require(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.ShortCutRedirectBlock(var_name: str)[source]

Bases: Block

will_accept(ctx: Context) → bool[source]

Describes whether the block is valid for the given Context.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: Whether the block should be processed for this Context.
Return type:: bool

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.StopBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The stop block stops tag processing if the given parameter is true. If a message is passed to the payload it will return that message.

Usage: {stop(<bool>):[string]}

Aliases: halt, error

Payload: string, None

Parameter: bool

Examples:

{stop({args}==):You must provide arguments for this tag.}
# enforces providing arguments for a tag

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.StrfBlock(*args, **kwargs)[source]

Bases: Block

The strf block converts and formats timestamps based on strftime formatting spec. Two types of timestamps are supported: ISO and epoch. If a timestamp isn’t passed, the current UTC time is used.

Invoking this block with Unix-specific services will return the current Unix timestamp.

Usage: {strf([timestamp]):<format>}

Aliases: unix

Payload: format, None

Parameter: timestamp

Example:

{strf:%Y-%m-%d}
# 2021-07-11

{strf({user(timestamp)}):%c}
# Fri Jun 29 21:10:28 2018

{strf(1420070400):%A %d, %B %Y}
# Thursday 01, January 2015

{strf(2019-10-09T01:45:00.805000):%H:%M %d-%B-%Y}
# 01:45 09-October-2019

{unix}
# 1629182008

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.StrictVariableGetterBlock(*args, **kwargs)[source]

Bases: Block

The strict variable block represents the adapters for any seeded or defined variables. This variable implementation is considered “strict” since it checks whether the variable is valid during will_accept() and is only processed if the declaration refers to a valid variable.

Usage: {<variable_name>([parameter]):[payload]}

Aliases: This block is valid for any variable name in Response.variables.

Payload: Depends on the variable’s underlying adapter.

Parameter: Depends on the variable’s underlying adapter.

Examples:

{=(var):This is my variable.}
{var}
# This is my variable.

will_accept(ctx: Context) → bool[source]

Describes whether the block is valid for the given Context.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: Whether the block should be processed for this Context.
Return type:: bool

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.SubstringBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The substring block extracts a specific portion of the payload text using 0-based indexing. It supports both a single starting index and a specific range of characters.

Important

Behavior:

If a single index is provided, it returns all characters from that position to the end (counting from the start).
From nth position (index) to end.
If a range is provided using - (e.g., 0-5), it returns the characters from the start index to the end index but without including the end th index.

Usage: {substr(<start[-end]>):<text>}

Aliases: substring

Payload: text (to extract from)

Parameter: A single integer for start, or a hyphenated range (start-end).

Examples:

{substr(7):Hello, World!}
# World!
Explanation:
# - Skips up to index 7 ("Hello, ") and starts at "W" (index 7). As 7th index is inclusive.

{substr(1-4):Hello}
# ell
Explanation:
# - Skips the first character ("H" at index 0) and starts at "e" (index 1).
# - Stops at index 4 (exclusive), so it doesn't include "o" (index 4).

{substr(7-12):Hello, World!}
# World

{substr(7):TagScript is powerful}
# pt is powerful
Explanation:
# - Skips up to index 7 ("TagScri") and starts at "pt" (index 7).
# - Indexing: T(0)a(1)g(2)S(3)c(4)r(5)i(6)p(7). So at 7 it starts at pt.

Note

For Single Index: Starting index is inclusive to the end of the string.
For Range: Starting index is inclusive, while the ending index is exclusive.
Negative indices are not supported.

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.URLEncodeBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

This block will encode a given string into a properly formatted url with non-url compliant characters replaced. Using + as the parameter will replace spaces with + rather than %20.

Usage: {urlencode(["+"]):<string>}

Payload: string

Parameter: “+”, None

Examples:

{urlencode:covid-19 sucks}
# covid-19%20sucks

{urlencode(+):im stuck at home writing docs}
# im+stuck+at+home+writing+docs

# the following tagscript can be used to search up tag blocks
# assume {args} = "command block"
# <https://cool-cogs.readthedocs.io/en/latest/search.html?q={urlencode(+):{args}}&check_keywords=yes&area=default>
# <https://cool-cogs.readthedocs.io/en/latest/search.html?q=command+block&check_keywords=yes&area=default>

process(ctx: Context) → str[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.UpperBlock(*args, **kwargs)[source]

Bases: Block

Converts the given text to uppercase.

Usage: {upper([text])}

Aliases: uppercase, upper

Payload: None

Parameter: text

Examples:

The text is {upper(ThIs Is A TeXt)}!
# The text is THIS IS A TEXT!

{=(args):Hello World}
You have entered {upper({args})}!
# You have entered HELLO WORLD!

process(ctx: Context) → str[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.LowerBlock(*args, **kwargs)[source]

Bases: Block

Converts the given text to lowercase.

Usage: {lower([text])}

Aliases: lowercase, lower

Payload: None

Parameter: text

Examples:

The text is {lower(ThIs Is A TeXt)}!
# The text is this is a text!

{=(args):HELLO WORLD}
You have entered {lower({args})}!
# You have entered hello world!

process(ctx: Context) → str[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.CountBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The count block counts occurrences of a substring within a message. The search is case sensitive and includes overlapping substrings.

A payload (the message to search in) is required. Optionally, pass the text to search for as a parameter. If no parameter is provided, the block counts the number of words in the message (spaces + 1).

Usage: {count([text]):<message>}

Aliases: None

Payload: message (required)

Parameter: text (optional, the substring to count)

Examples:

{count(Tag):TagScriptEngine}
# 1

{count(Tag):Tag Script Engine TagScriptEngine}
# 2

{count:hello world}
# 2 (word count: 1 space + 1)

{count(123)}
# Returns {count(123)} — rejected because no payload was provided

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.LengthBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The length block returns the character count of the given text.

Usage: {length(<text>)}

Aliases: len

Payload: None

Parameter: text (required)

Examples:

{len(TagScriptEngine)}
# 15

{len(hello world)}
# 11

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.JoinBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The join block replaces every space in the payload with the parameter string. These blocks only function in Tags.

The parameter must be set, even if it is an empty string. Cannot use the symbols ) or } as parameters.

Usage: {join(<string>):<payload>}

Aliases: None

Payload: payload

Parameter: string (required, can be empty)

Examples:

{join(_):hello friends}
# hello_friends

{join():an example sentence}
# anexamplesentence

{join(-):cool aid man}
# cool-aid-man

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.ListBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The list block returns the element in the payload that corresponds to the index value in the parameter. The block returns null if the index is out of bounds.

List and Cycle blocks are another way to parse through a list of values in TagScript. They both strictly use either commas , or tildes ~ as the delimiters for the list placed in the block’s payload. Use tildes when elements contain commas. These blocks only function in Tags.

Lists use 0 as the index for the first element. Negative values allow for backward parsing. The block will return an error message if the value in the parameter is not a number.

Usage: {list(<index>):<elem>,<elem2>,...}

Aliases: None

Payload: list of elements (comma or tilde separated)

Parameter: index

Examples:

{list(0):Pizza~Burger~Pie~Chips~Lasagna}
# Pizza

{list(3):Pizza~Burger~Pie~Chips~Lasagna}
# Chips

{list(-1):Apple,Banana,Cherry}
# Cherry

{list(10):Apple,Banana,Cherry}
# (returns null — index out of bounds)

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.CycleBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The cycle block returns the element in the payload that corresponds to the index value in the parameter. If the index is out of bounds, it loops around using modulo (index % list_length).

List and Cycle blocks are another way to parse through a list of values in TagScript. They both strictly use either commas , or tildes ~ as the delimiters for the list placed in the block’s payload. Use tildes when elements contain commas. These blocks only function in Tags.

Cycles use 0 as the index for the first element. Negative values allow for backward parsing. The block will return an error message if the value in the parameter is not a number.

Usage: {cycle(<index>):<elem>,<elem2>,...}

Aliases: None

Payload: list of elements (comma or tilde separated)

Parameter: index

Examples:

{cycle(1):Cake,Candy,Chips,Cookies,Donut}
# Candy

{cycle(13):Cake,Candy,Chips,Cookies,Donut}
# Cookies
# (The list has 5 elements. 13 modulo 5 = 3. Index 3 is "Cookies".)

{cycle(3):0,1,2}
# 0
# (3 modulo 3 = 0. Index 0 is "0".)

Negative indices:
{cycle(-1):Apple,Banana,Cherry}
# Cherry

{cycle(-69):Charlie,Aid,Bob,Dave,Eve,Phen,Steve,Tom,Wendy,Xavier}
# Aid
# (-69 modulo 10 = 1. Index 1 is "Aid".)

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.

class TagScriptEngine.block.OrdinalBlock(*args, **kwargs)[source]

Bases: VerbRequiredBlock

The ordinal block returns the number in the payload with the correct ordinal abbreviation following it.

Usage: {ordinal:<number>}

Aliases: ord

Payload: number

Parameter: None

Examples:

{ordinal:101}
# 101st

{ord:22}
# 22nd

{ordinal:3}
# 3rd

{ord:456}
# 456th

{ordinal:11}
# 11th

{ord:12}
# 12th

process(ctx: Context) → str | None[source]

Processes the block’s actions for a given Context.

Subclasses must implement this.

Parameters:: ctx (Context) – The context object containing the TagScript Verb.
Returns:: The block’s processed value.
Return type:: Optional[str]
Raises:: NotImplementedError – The subclass did not implement this required method.