-
Notifications
You must be signed in to change notification settings - Fork 35
JagTag
Several parts of Spectra utilize JagTag notation, such as tags, welcome messages, and leave messages. JagTag is a text-processing language that can be customized for different applications. For full documentation on the JagTag java library, check out the repository. Please check out the documentation on methods available in Spectra here, as well as the examples below!
These methods deal with Discord entities, like users, channels, etc.
{user} - Returns the name of the user that ran the tag
{user:SEARCH} - Returns the name of the user found based on the given search
Example:
I found {user:jagro} and me, {user}
Input:%tag example
Output:I found jagrosh and me, Minn
{nick} - Returns the nickname of the user that ran the tag
{nick:SEARCH} - Returns the nickname of the user found based on the given search
Example:
{nick:jagro} is the nickname of jagrosh, and {nick} is my nickname
Input:%tag example
Output:Midna is the nickname of jagrosh, and TheWiki is my nickname
{discrim} - Returns the discriminator of the user that ran the tag
{discrim:SEARCH} - Returns the discriminator of the user found based on the given search
Example:
jagrosh's discrim is {discrim:jagro}, but mine is {discrim}
Input:%tag example
Output:jagrosh's discrim is 4824, but mine is 1337
{avatar} - Returns the url of the avatar of the user that ran the tag
{avatar:SEARCH} - Returns the url of the avatar of the user found based on the given search
Example:
My avatar: {avatar}
Input:%tag example
Output:My avatar: http://website.com/image.png
{creation:ENTITY ID} - Returns the creation time of an entity based on its ID
Example:
The account was created {creation:113156185389092864}
Input:%tag example
Output:The account was created Mon, 9 Nov 2015 06:02:16 GMT
{userid} - Returns the id of the user running the tag
Example:
My id is {userid}
Input:%tag example
Output:My id is 113156185389092864
{atuser} - Returns a ping of the user running the tag. This is equivalent to <@{userid}>
Example:
Ping me {atuser}
Input:%tag example
Output:Ping me @jagrosh
{server} - Returns the name of the server
Example:
Welcome to {server}!
Input:%tag example
Output:Welcome to jagrosh's Bots!
{serverid} - Returns the ID of the server
Example:
This server's ID is {serverid}
Input:%tag example
Output:This server's ID is 147698382092238848
{servercount} - Returns the number of members on the server
Example:
There's {servercount} members
Input:%tag example
Output:There's 1931 members
{servericon} - Returns the icon url of the server
Example:
Icon: {servericon}
Input:%tag example
Output:Icon: http://website.com/icon.png
{channel} - Returns the name of the current channel
Example:
This is #{channel}
Input:%tag example
Output:This is #testing_calm
{channelid} - Returns the id of the current channel
Example:
This channel ID is {channelid}
Input:%tag example
Output:This channel ID is 147698606739161088
{randuser} - Returns the name of a random user on the server
Example:
Send a message to {randuser} please
Input:%tag example
Output:Send a message to Pointy please
{randonline} - Returns the name of a random online user on the server
Example:
Hey look! {randonline} is online!
Input:%tag example
Output:Hey look! Fi is online!
{randchannel} - Returns the name of a random channel on the server
Example:
Lets see what's going on in #{randchannel}
Input:%tag example
Output:Let's see what's going on in #support
Arguments deal with input that is provided when the jagtag code is run. For example, when using a tag, users can provide input to the tag (after the name) and this input is provided as arguments.
{args} - Any additional text that is passed in
Example:
You said "{args}".
Input:%tag example I am a potato
Output:You said "I am a potato"
{argslen} - The number of arguments provided (split on any whitespace)
Example:
You said {argslen} words
Input:%tag example This is a cool tag
Output:You said 5 words
{arg:NUMBER} - Returns the numbered argument. This is zero-based indexing, so the first argument is {arg:0}. If the number provided is higher than the total number of arguments, it is taken modulus the number of arguments so it will always be valid.
Example:
Your 3rd word was: {arg:2}
Input:%tag example I said some words
Output:Your 3rd word was: some
Functional methods deal with conditional statements, mathematics, and random numbers
{note:TEXT} - Comment that gets removed at runtime
Example:
{note:This is a cool tag} Hi there!
Input:%tag example
Output:Hi there!
{choose:OPTION 1|OPTION 2|OPTION 3...} - Chooses randomly between several options. At least one item must be included.
Example:
It's going to be {choose:sunny|rainy|stormy} today
Input:%tag example
Output:It's going to be rainy today
{range:NUMBER|NUMBER} - Picks a random number in the provided range. This is inclusive for the lower number and exclusive for the higher number. For example, {range:3|7} can return 3, 4, 5, or 6
Example:
There is a {range:0|101}% chance of this
Input:%tag example
Output:There is a 57% chance of this
{if:ITEM|CONDITIONAL|ITEM|then:TEXT|else:TEXT} - Compares two items. If both items are numbers, they are compared using their values.
| Comparator | Text | Number |
|---|---|---|
| = | Exact same text | Exact same value |
| < | Alphabetical comparison | Numeric comparison |
| > | Alphabetical comparison | Numeric comparison |
| ~ | Case-insensitive text | Approximate same value (2 decimal places) |
| ? | Regex matching | N/A |
Example:
{if:this|?|th.*|then:The word starts with th|else:The word doesn't}
Input:%tag example
Output:The word starts with th
{math:NUMBER|EXPRESSION|NUMBER|EXPRESSION|NUMBER...} - Evaluates mathematics. Available expressions are + (addition), - (subtraction), * (multiplication), / (division), % (modulus), ^ (exponentiation)
Example:
There are {math:60|*|60|*|24} seconds in a day
Input:%tag example
Output:There are 86400 seconds in a day
{abs:NUMBER} - Takes the absolute value of a number
Example:
Absolute value of -6 is {abs:-6}
Input:%tag example
Output:Absolute value of -6 is 6
{floor:NUMBER} - Rounds a number down
Example:
Floor of 8.3 is {floor:8.3}
Input:%tag example
Output:Floor of 8.3 is 8
{ceil:NUMBER} - Rounds a number up
Example:
Ceiling of 4.1 is {ceil:4.1}
Input:%tag example
Output:Ceiling of 4.1 is 5
{round:NUMBER} - Rounds a number up or down based on the decimal value
Example:
5.6 rounded is {round:5.6}
Input:%tag example
Output:5.6 rounded is 6
{sin:NUMBER} - Takes sine of radian value
Example:
Sine of 1.1 is {sin:1.1}
Input:%tag example
Output:Sine of 1.1 is 0.89120736006
{cos:NUMBER} - Takes cosine of radian value
Example:
Cosine of 1.1 is {cos:1.1}
Input:%tag example
Output:Cosine of 1.1 is 0.45359612142
{tan:NUMBER} - Takes tangent of radian value
Example:
Tangent of 1.1 is {tan:1.1}
Input:%tag example
Output:Tangent of 1.1 is 1.96475965725
{base:NUMBER|OLD BASE|NEW BASE} - Converts a number from one base to another base
Example:
6 in binary is {base:6|10|2}
Input:%tag example
Output:6 in binary is 110
String methods are used for text manipulation
{lower:TEXT} - Makes a string all lowercase
Example:
{lower:wHOA thErE!}
Input:%tag example
Output:whoa there!
{upper:TEXT} - Makes a string all uppercase
Example:
{upper:wHOA thErE!}
Input:%tag example
Output:WHOA THERE!
{length:TEXT} - Returns the length of a string
Example:
"Hello" is {length:Hello} characters long
Input:%tag example
Output:"Hello" is 5 characters long
{url:TEXT} - Converts a string to standard URL UTF-8 encoding
Example:
http://lmgtfy.com/?q={url:Discord Bots}
Input:%tag example
Output:http://lmgtfy.com/?q=Discord+Bots
{replace:TEXT|with:TEXT|in:TEXT} - Replaces some text with other text in the provided text
Example:
{replace:hello|with:goodbye|in:Oh, hello! I say hello a lot!}
Input:%tag example
Output:Oh, goodbye! I say goodbye a lot!
{replaceregex:REGEX|with:TEXT|in:TEXT} - Replaces text matching a regex with other text in the provided text
Example:
{replaceregex:\d|with:#|in:I have 5 cats and 23 shirts}
Input:%tag example
Output:I have # cats and ## shirts
{substring:NUMBER|NUMBER|TEXT} - Takes a substring of a provided string. Numbers can be negative to work backwards from the end of a string. Like range:, lower number is inclusive and higher number is exclusive.
Example:
{substring:3|5|My Cool Text}
Input:%tag example
Output:Co
{oneline:TEXT} - Condenses all whitespace (including newlines) to simple spaces
Example:
Whoa this is a lot of space
Input:%tag example
Output:Whoa this is a lot of space
{hash:TEXT} - Returns a hash code for the provided text. This often, but not completely unique
Example:
Your hash is: {hash:my text here}
Input:%tag example
Output:Your hash is: -292243057
These methods are designed for dealing with time and time formatting
{now} - Shows the current time, formatted to RFC 1123
{now:FORMAT} Shows the current time, formatted as specified. See the DateTimeFormatter Patterns documentation for available format symbols
Example:
The current year is {now:YYYY}
Input:%tag example
Output:The current year is 2017
{time:EPOCH MILLIS|FORMAT} - Parses the provided epoch milliseconds to the specified formatted time. If the format is not provided, it uses RFC 1123
Example:
Current minutes: {time:1496519175495|mm}
Input:%tag example
Output:Current minutes: 46
These methods are for dealing with variables. Variable values are not persistent after tags are run; these are for in-line changes only.
{set:NAME|VALUE} - Sets a variable to a value. This doesn't return any string
Example:
{set:count|80} I'm setting the count to 80
Input:%tag example
Output:I'm setting the count to 80
{get:NAME} - Recalls a variable. The variable must exist.
Example:
{set:food|Pizza} My favorite food is {get:food}
Input:%tag example
Output:My favorite food is Pizza
-
Mention a user:
<@{userid}> -
Give a response only if one is provided:
{if:{argslen}|=|0|then:Please say something|else:{nick} said: {args}} -
Give the number of users in a server only if it is a multiple of 100:
{if:{math:{servercount}|%|100}|=|0|then:That's {servercount} users!|else:} -
Pick a random phrase:
I ate {choose:too many|a lot of|a big pile of|{range:0|100}|2 and a half} cookies!