TAGSCRIPT

Preface

TagScript is part of RAC's tag commands. Use !!tag <name> [arguments...] to run tags. See the command list for more information.

Syntax

Parameters

Parameters are options that configure a function. When a function accepts parameters, they appear in parentheses after its name, as in {function(parameters):payload}. The parameter notation below tells you which options are required or optional.

Payloads

A payload is the content a function acts on or uses. Depending on the function, it may follow a colon, as in {function:payload}, appear in parentheses, as in {function(payload)}, or follow the parameters after a colon, as in {function(parameters):payload}. Not every function accepts both parameters and a payload. See the list below for information on a specific function.

Parsing Behavior

• Function names are case-insensitive. However, they are whitespace-sensitive. Take care to remove whitespace around function names, i.e., { function }, otherwise the parser will not see them.
• Nonexistent tag functions are not parsed and are left as-is.
• Unbalanced braces, such as {function}}, are left as-is. However, they may break other TagScript functions if nested inside a function that takes parameters or payloads.
• Functions that require parameters or payloads, but do not receive any, are not parsed.
• Comments are ignored by the parser and removed entirely from the output.

Comments & Escaping

Comments are set via {note:your comment} or{comment:your comment}. They are entirely ignored by the parser and additionally removed from the output, provided that the TagScript executed successfully.

To escape TagScript blocks (outputting without running), use {ignore:{some_function}}. The payload is returned as-is and the parser will not evaluate anything inside. However, the braces will still need to be balanced.

Arguments

Arguments are optional text passed to the !!tag command, after the name parameter. You can use {message(args)} to access the full string. An empty string will be returned if the user did not pass any arguments when running the tag.

Control

If-Statements

If-statements are written in the form {if(VALUE OPERATOR VALUE):true branch|false branch}. Both values are evaluated first and then compared after. Whitespace between the operators and value is stripped automatically.

Below is a list of valid comparison operators:

Numeric operators will attempt to coerce both values into floats. The false branch will be executed as a fallback if the coercion fails.

For Loops

For loops are written in the form {for(INTEGER):do whatever}. INTEGER is limited to 0 <= i <= 64. A value above or below those limits will throw an error. For loops implicitly create an integer-type variable named index, accessible through {get(index)}.

Stop Statement

Stop statements prematurely end TagScript execution with an optional message, provided that a condition is true. They are written as {stop(CONDITION):MESSAGE}. CONDITION retains the comparison operators from if-statements, excluding ===, !==, and ~=.

Variables

Variables are set through the function {set(NAME):VALUE}. name has a limit of 32 characters, and value has a limit of 1,024 characters. Breaking either of these limits will throw an error. Getting defined variables is done through {get(NAME)}, and trying to fetch an undefined variable will throw an error. Similarily, deleting variables is done through {delete(NAME)}, however no error is thrown for attempting to use an undefined variable. There is a limit of 16 total variables that can be defined.

Exceptions

When a TagScript block fails, the parser immediately stops further execution, and the bot will reply with an error message through an embed.

To catch errors, use the try-except block: {try:an error will happen|errored out}. A variable named error will be implicitly created if the error branch of the try-except statement is reached, containing the error string. Access it through {get(error)} in the error branch.

Stop statements can be used to handle exceptions gracefully rather than having the bot throw a TagScript execution error. Consider {try:value is {get(undefined)}|{stop({get(error)}!=):something errored out}}. {get(undefined)} will throw an error that is caught and assigned to the error variable by the try statement, which is then compared against an empty string in the stop statement. The comparison succeeds and something errored out is displayed.

Markers

• DEPRECATED means that a function may be removed soon or have breaking changes applied to it.