Blocks
All Block
- class bTagScript.block.AllBlock[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.
Any Block
- class bTagScript.block.AnyBlock[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(hi=={args}|hello=={args}|heyy=={args}):Hello {user}!|How rude.} If {args} is hi Hello _Leg3ndary#0001! If {args} is what's up! How rude.
Assignment Block
Blacklist Block
- class bTagScript.block.BlacklistBlock[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
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.}
Break Block
- class bTagScript.block.BreakBlock[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.}
Command Block
- class bTagScript.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"
Cooldown Block
- class bTagScript.block.CooldownBlock[source]
Bases:
VerbRequiredBlock
The cooldown block implements cooldowns when running a tag. The parameter requires 2 values to be passed:
rate
andper
integers. Therate
is the number of times the tag can be used everyper
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 samerate
andper
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
andretry_after
.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.
Embed Block
- class bTagScript.block.EmbedBlock[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.
Usage:
{embed(<json>)}
Payload:
None
Parameter:
json
{embed({"title":"Hello!", "description":"This is a test embed."})} {embed({ "title":"Here's a random duck!", "image":{"url":"https://random-d.uk/api/randomimg"}, "color":15194415 })}
Manual
The following embed attributes can be set manually:
title
description
color
url
thumbnail
image
field
- (See below)
Adding a field to an embed requires the payload to be split by
|
, 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
{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}
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.
:: tagscript:
{embed({{"fields":[{"name":"Field 1","value":"field description","inline":false}]})} {embed(title):my embed title}
If Block
- class bTagScript.block.IfBlock[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(63=={args}):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.
Loose Variable Block
- class bTagScript.block.LooseVariableGetterBlock[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 thanwill_accept()
. You may also define variables here with {$<variable name>:<value>}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:
{=(example):This is my variable.} {example} This is my variable. {$variablename:This is another variable.} {variablename} This is another variable.
Math Block
- class bTagScript.block.MathBlock[source]
Bases:
Block
A math block is a block that contains a math expression. Will write out everything later bleh
Usage:
{math:<expression>}
Aliases:
math, m, +, calc
Payload:
expression
Parameter: None
Examples:
{m:2+3} 5.0 {math:7(2+3)} 42.0 {math:trunc(7(2+3))} 42
Override Block
- class bTagScript.block.OverrideBlock[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]}
Aliases:
bypass
Payload:
command
Parameter:
"admin", "mod", "permissions"
Examples:
{override} overrides all commands and permissions {override(admin)} overrides commands that require the admin role {bypass(permissions)} {bypass(mod)} overrides commands that require the mod role or have user permission requirements
Random Block
- class bTagScript.block.RandomBlock[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. You can weight options differently by adding a weight and | before the item.Usage:
{random([seed]):<list>}
Aliases:
#, rand
Payload:
list
Parameter:
seed
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 {#:5|Cool,3|Lame} 5 to 3 chances of being cool vs lame
Range Block
- class bTagScript.block.RangeBlock[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
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.
Redirect Block
- class bTagScript.block.RedirectBlock[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)}
Replace Block
- class bTagScript.block.ReplaceBlock[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:
sub
Payload: message
Parameter: original, new
{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
Require Block
- class bTagScript.block.RequireBlock[source]
Bases:
VerbRequiredBlock
The require block will attempt to convert the given parameter into a channel role or member, 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, member>):[response]}
Aliases:
whitelist
Payload:
response
Parameter:
role, channel, member
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.}
ShortCutRedirect Block
STRF Block
- class bTagScript.block.StrfBlock[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
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
Strict Variable Block
- class bTagScript.block.StrictVariableGetterBlock[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:
{=(example):This is my variable.} {example} This is my variable.
URL Encode Block
- class bTagScript.block.URLEncodeBlock[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
Example:
{urlencode:covid-19 sucks} covid-19%20sucks {urlencode(+):im stuck at home writing docs} im+stuck+at+home+writing+docs You can use this to search up blocks Eg if {args} is command block <https://btagscript.readthedocs.io/en/latest/search.html?q={urlencode(+):{args}}&check_keywords=yes&area=default> <https://btagscript.readthedocs.io/en/latest/search.html?q=command+block&check_keywords=yes&area=default>
URL Decode Block
- class bTagScript.block.URLDecodeBlock[source]
Bases:
VerbRequiredBlock
This block will decode a given url into a string with non-url compliant characters replaced. Using
+
as the parameter will replace spaces with+
rather than%20
.Usage:
{urldecode(["+"]):<string>}
Payload: string
Parameter: “+”, None
Examples:
{urldecode:covid-19%20sucks} covid-19 sucks {urldecode(+):im+stuck+at+home+writing+docs} im stuck at home writing docs
This block is just the reverse of the urlencode block
Length Block
- class bTagScript.block.LengthBlock[source]
Bases:
VerbRequiredBlock
The length block will check the length of the given String. If a parameter is passed in, the block will check the length based on what you passed in, w for word, s for spaces. If you provide an invalid parameter, the block will return -1.
Usage:
{length(["w", "s"]):<text>}
Aliases:
len
Payload:
text
Parameter:
"w", "s"
{length:TagScript} 9 {len(w):Tag Script} 2 {len(s):Hello World, Tag, Script} 3 {len(space):Hello World, Tag, Script} -1
Count Block
- class bTagScript.block.CountBlock[source]
Bases:
VerbRequiredBlock
The count block will count how much of text is in message. This is case sensitive and will include substrings, if you don’t provide a parameter, it will count the spaces in the message.
Usage:
{count([text]):<message>}
Aliases:
None
Payload:
message
Parameter: text
{count(Tag):TagScript} 1 {count(Tag):Tag Script TagScript} 2 {count(t):Hello World, Tag, Script} 1 as there's only one lowercase t in the entire string
OrdinalAbbreviation Block
- class bTagScript.block.OrdinalAbbreviationBlock[source]
Bases:
Block
The ordinalabbreviation block returns the ordinal abbreviation of a number. If a parameter is provided, it must be, one of, c, comma, indicator, i Comma being adding commas every 3 digits, indicator, meaning the ordinal indicator. (The st of 1st, nd of 2nd, etc.)
The number may be positive or negative, if the payload is invalid, -1 is returned.
Usage:
{ord(["c", "comma", "i", "indicator"]):<number>}
Aliases:
None
Payload:
number
Parameter:
"c", "comma", "i", "indicator"
{ord:1000} 1,000th {ord(c):1213123} 1,213,123 {ord(i):2022} 2022nd
Debug Block
- class bTagScript.block.DebugBlock[source]
Bases:
Block
The debug block allows you to debug your tagscript quickly and easily, it will save the output to the debug_var key in the response dict. Separate the variables you want to include or exclude with a comma or a tilde.
If no parameters are provided in addition to no payload, all variables will be included. If no parameters are provided and a payload is provided, it will assume you want to include those variables.
Usage:
{debug(["i", "include", "e", "exclude"]):<variables>}
Aliases:
None
Payload:
variables
Parameter:
"i", "include", "e", "exclude"
Note
{debug} is the same as {debug(exclude):}
{debug:somevar~anothervar} is the same as {debug(include):somevar~anothervar}
Examples:
Note
THIS SHOULD ALWAYS BE PLACED AT THE VERY BOTTOM, IT WILL NOT RETURN ANYTHING UNDER IT.
Assuming we have the following tagscript, we first set the var something, then set parsed (using the dollar sign method), to Hello|World, (assume we actually wanted just the Hello but we forgot) {=(something):Hello/World} {$parsed:{something(1)}} {if({parsed}==Hello):Hello|Bye} Running this would provided the output Bye, using the debug block below: {debug} We'll get all the variables at their, "final state" This will be provided in a dict, which you can further parse and output to your liking. EG, in YAML format: something: Hello/World parsed: Hello/World This allow's you to see that you forgot to parse with a delimiter which will lead to easy fixing.
Comment Block
Bases:
Block
The comment block is literally just for comments, it will not be parsed, however it will be removed from your codes output.
Usage:
{comment([other]):[text]}
Aliases: /, Comment, comment, //
Payload:
text
Parameter:
other