TagScriptEngine Blocks

Core Blocks

Assignment Block

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

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

Cycle Block

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

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".)

List Block

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

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)

Random Block

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

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

Math Block

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

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

Range Block

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

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.

Control Blocks

If Block

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

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.

Break Block

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

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.}

All Block

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

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.

Any Block

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

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.

Fifty-fifty Block

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

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

Stop Block

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

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

String Blocks

Join Block

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

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

Replace Block

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

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

URLEncode Block

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

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>

Search Blocks

In Block

The in block checks if the parameter string is anywhere in the payload as a substring.

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

Aliases: None

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 Block

The contains block strictly checks if the parameter is in the payload, split by whitespace. This performs exact matching on whitespace-split words. For example, food will not match food. (with trailing punctuation).

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

Aliases: None

Payload: payload

Parameter: string

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

Index Block

The index block finds the location/index of the parameter in the payload, split by whitespace. If the parameter string is not found, it returns -1. This performs exact matching on whitespace-split words.

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

Aliases: None

Payload: payload

Parameter: string

Examples:
{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

Miscellaneous Blocks

Ordinal Block

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

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

Strftime Block

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

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 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

Substring Block

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

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.

Case Blocks

Upper Block

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

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!

Lower Block

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

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!

Counting Blocks

Count Block

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

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

Length Block

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

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