TagScriptEngine Blocks

Core Blocks

Assignment Block

class TagScriptEngine.AssignmentBlock

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

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

Aliases: assign, let, var

Payload: value

Parameter: name

Examples:

{=(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.

Random Block

class TagScriptEngine.RandomBlock

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

Range Block

class TagScriptEngine.RangeBlock

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

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

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

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

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

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

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

Example:

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

String Blocks

Replace Block

class TagScriptEngine.ReplaceBlock

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

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://phen-cogs.readthedocs.io/en/latest/search.html?q={urlencode(+):{args}}&check_keywords=yes&area=default>
# <https://phen-cogs.readthedocs.io/en/latest/search.html?q=command+block&check_keywords=yes&area=default>

Miscellaneous Blocks

Strftime Block

class TagScriptEngine.StrfBlock

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