Skip to content
John Grosh edited this page May 7, 2018 · 5 revisions

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!

Methods

Discord

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

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

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

Strings

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

Time

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

Variables

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


Examples

  • 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!
You can’t perform that action at this time.