Templates
All available data that can be used in YAGPDB's templating "engine" which is slightly modified version of Golang's stdlib text/template package; more in depth and info about actions, pipelines and global functions like printf, indexetc > https://golang.org/pkg/text/template/
Put curly brackets around the data you want to formulate as template like this: {{ .User.Username }}
This {{ ... }} syntax of having two curly brackets aka braces around context is always necessary to form a template's control structure with methods and functions stated below.
Data passed around template pipeline can be initialized as a variable to capture it > (in EBNF syntax) $variable := value. Previously declared variable can also be assigned with new data > $variable = value. Variable scope extends to the {{ end }} action of the control structure.
If you want to join different data objects (e.g. to wrap toString in joinStr around .Guild.MemberCount), you use round brackets aka parentheses as delimiters:
{{ joinStr "" "Our member count is " (toString .Guild.MemberCount) "!" }}
Templating system uses standard ASCII quotation marks:
0x22 > " for straight double quotes, 0x27 > 'for apostrophes and 0x60 ` for backticks;
so make sure no "smart-quotes" are being used.
"Go is all about type... Type is life." // William Kennedy
Everything in Go is passed by value, as in C and in all languages descending from C.
Many problems start with different kinds of type the user has as values and what is needed for arguments. YAGPDB usually states that in error message - what went wrong with type e.g. CC #42:24:123 ... error calling lt: incompatible types for comparison tells you that CC #42 has an error on line 24 and at entry point position 123 due to different types presented for comparison action.
To see of what type a variable or function's return is, use printf "%T", for example > {{ printf "%T" currentTime }} will output the type time.Time.
The dot {{ . }} encompasses all active data available for templating system.
From official docs > "Execution of the template walks the structure and sets the cursor, represented by a period '.' and called "dot", to the value at the current location in the structure as execution proceeds." All following fields/methods/objects like User/Guild/Member/Channel etc are all part of that dot-structure and there are some more in tables below.
Field | Description |
.CCID | The ID of currently executing custom command in type of int64. |
.IsPremium | Returns boolean true/false whether guild is premium of YAGPDB or not. |
Field | Description |
.User | The user's username together with discriminator. |
.User.String | The user's username together with discriminator as string-type. |
.User.Username | The user's username. |
.User.ID | The user's ID. |
.User.Discriminator | The user's discriminator (The four digits after a person's username). |
.User.Avatar | The user's avatar ID. |
.User.AvatarURL "256" | Gives the URL for user's avatar, argument "256" is the size of the picture and can increase/decrease twofold (e.g. 512, 1024 or 128, 64 etc.). |
.User.Bot | Determines whether the target user is a bot - if yes, it will return True. |
.User.Mention | Mentions user. |
.RealUsername | Only works with join and leave messages (not join dms). This can be used to send the real username to a staff channel when invites are censored. |
.UsernameHasInvite | Only works with join and leave messages (not join dms). It will determine does the username contain an invite link. |
Function | Description |
| Function that can be used to retrieve .User object from a mention or userID.
|
| Returns a slice of type
|
| Same as |
User object in Discord documentation.
Field | Description |
.Guild.ID | Outputs the ID of the guild. |
.Guild.Name | Outputs the name of the guild. |
.Guild.Icon | Outputs the ID of the guild's icon. |
.Guild.Region | Outputs the region of the guild. |
.Guild.AfkChannelID | Outputs the AFK channel ID. |
.Guild.OwnerID | Outputs the ID of the owner. |
.Guild.JoinedAt | Outputs the timestamp when YAGPDB joined the guild. To convert it to type Time, use .Parse method > |
.Guild.AfkTimeout | Outputs the time when a user gets moved into the AFK channel while not being active. |
.Guild.MemberCount | Outputs the number of users on a guild. |
.Guild.VerificationLevel | Outputs the required verification level for the guild. |
.Guild.EmbedEnabled | Outputs whether guild is embeddable (e.g. widget) or not, true / false. |
.Guild.Roles | Outputs all roles and indexing them gives more information about the role. For exampe |
Guild object in Discord documentation.
Field | Description |
.Member.JoinedAt | When member joined the guild/server of type Timestamp. .Parse method will convert this to of type Time. |
.Member.Nick | The nickname for this member. |
.Member.Roles | A list of role IDs that the member has. |
.Member.User | Underlying user on which the member is based on. |
Function | Description |
| Edits triggering user's nickname, argument has to be of type string. YAGPDB must be above the roles user's having. |
| Function returns Member object having above methods.
|
| Returns the count of online users/members on current server. |
| Returns the count of online bots. |
Member object in Discord documentation.
Field | Description |
.Channel.Name | The Name of the channel. |
.Channel.ID | The ID of the channel. |
.Channel.ParentID | The ID of the channel's parent (category), returns 0 if none. |
.Channel.Topic | The Topic of the channel. |
.Channel.NSFW | Outputs whether this channel is NSFW or not. |
Function | Description |
| Function edits channel's name. |
| Function edits channel's topic/description.
|
Channel object in Discord documentation.
Field | Description |
.Message.ID | ID of the message. |
.Message.ChannelID | Channel id this message is in. |
.Message.Author | Author of the message (User object). |
.Message.Timestamp | Timestamp of the message in type timestamp (use .Message.Timestamp.Parse to get type time and .Parse.String method returns type string). |
.Message.Attachments | Attachments to this message (slice of attachment objects). |
.Message.Embeds | Embeds on this message (slice of embed objects). |
.Message.Mentions | Users this message mentions. |
.Message.Reactions | Reactions on this message (only available from getMessage). |
.Message.Content | Text content on this message. |
.Args | List of everything that is passed to .Message.Content. .Args is a slice of type string. |
.Cmd | .Cmd is of type string and shows all arguments that trigger custom command, part of .Args. Starting from |
.CmdArgs | List of all the arguments passed after |
.StrippedMsg | "Strips" or cuts off the triggering part of the message and prints out everything else after that. Bare in mind, when using regex as trigger, for example |
Message object in Discord documentation.
More information about the Message template can be found here.
This is available and part of the dot when reaction trigger type is used.
Field | Description |
.Reaction | Returns reaction object which has following fields |
.ReactionMessage | Returns the message object reaction was added to.
Returns emoji count and their name. |
.ReactionAdded | Returns a boolean true/false indicating whether reaction was added or removed. |
Reaction object in Discord documentation.
Time in general uses Golang's time package library > https://golang.org/pkg/time/#time and also this although slightly different syntax all applies here > https://gobyexample.com/time.
Field | Description |
.TimeHour | Variable of time.Duration type and returns 1 hour > |
.TimeMinute | Variable of time.Duration type and returns 1 minute > |
| Variable of time.Duration type and returns 1 second > |
Function | Description |
| Gets the current time, value is of type time; which can be used in a custom embed. More info here. |
| Outputs given time in RFC822 formatting, first argument |
| Returns |
| Sames as |
| Sames as both humanize functions above, this time duration is given in seconds - e.g. |
| Returns time has passed since given argument of type Time in human readable format - e.g. |
| Returns new time object in UTC using following syntax... all arguments need to be of type int, for example > |
To demonstrate humanizeDurationHours and also how to parse a timestamp, output will be like
whoiscommand shows user's join server age.{{ humanizeDurationHours (currentTime.Sub .Member.JoinedAt.Parse) }}
Function | Description |
| Converts something into a string. Usage: |
| Converts something into an integer. Usage: |
| Converts something into an int64. Usage: |
| Converts argument (number of string) to type float64. Usage: |
| Converts argument (number or string) to type Duration, usable in time operations. Usage: |
| Traverses given |
To demonstrate toDuration, outputs 12 hours from current time in UTC.
{{ (currentTime.Add (toDuration (mult 12 .TimeHour) ) ).Format "15:04" }}
Function | Description |
| Joins several strings into one, separated by the first arg |
| Converts the string to lowercase. |
| Converts the string to uppercase. |
| Outputs the "string" after cutting/slicing off integer (numeric) value of symbols (actually starting the string's index from integer through integer2) - e.g.
|
| Escapes the string so it can be safely placed inside a URL path segment - e.g. "Hello, YAGPDB!" becomes "Hello%2C%20YAGPDB%21" |
| Splits given |
| Returns string with the first letter of each word capitalized. |
| Compares string to regex pattern and returns first match. |
| Adds all regex matches from the string to a slice. Example in section's Snippets. |
| Returns whole-pattern matches and also the sub-matches within those matches as slices inside a slice. |
| Replaces string1 contents with string2 at regex match point. |
With regular expression patterns - when using quotes you have to "double-escape" metacharacters starting with backslash or use backquotes/ticks to simplify this. {{ reFind "\\d+" (toString 42) }} versus {{ reFind `\d+` (toString 42) }}
{{ $args:= (joinStr " " (slice .CmdArgs 1) ) }}Saves all the arguments except the first one to a variable$args.To demonstrate usage of split function. >
{{ $x := "Hello, World, YAGPDB, here!" }} {{ range $k, $v := (split $x ", ") }}Word {{ $k }}: __{{ $v }}__ {{ end }}To demonstrate usage of reFindAll. >
Before regex: {{ $msg := "1 YAGPDB and over 100000 servers conqured." }} {{ $re2 := reFindAll "[0-9]+" $msg }} {{ $msg }} After regex matches: {{ joinStr " " "Only" (index $re2 0) "YAGPDB and already" (index $re2 1) "servers captured."}}
Function | Description |
| Returns x + y + z + ..., detects first number type; is it integer or float and based on that adds. (use |
| Returns x - y -z - ... Works like add, just subtracts. |
| Multiplication, like |
| Division, like |
| Meant specifically for floating point numbers division. |
| Mod returns the floating-point remainder of x/y. |
| Returns a random integer between 0 and stop, or start - stop if two args are provided. Result will be |
| Returns the nearest integer, rounding half away from zero. Regular rounding > 10.4 is 10 and 10.5 is 11. All round functions return type float64, so use conversion functions to get integers. For more complex rounding, example in section's Snippets. |
| Returns the least integer value greater than or equal to input or rounds up. |
| Returns the greatest integer value less than or equal to input or rounds down. |
| Returns the nearest integer, rounding ties to even.
|
| Returns the square root of a number.
|
{{ $d := randInt 10 }}Stores random int into variable$d(a random number from 0-9).To demonstrate rounding float to 2 decimal places.
{{ div (round (mult 12.3456 100) ) 100 }}returns 12.35{{ div (roundFloor (mult 12.3456 100) ) 100 }}returns 12.34
Function | Description |
| Sends the user a direct message, only one DM can be sent per template (accepts embed objects). random adjective. |
| Sends |
| Same as |
| Sends |
| Same as |
| Edits the message in channel, channel can be either |
| Edits the message in channel and has same logic in escaping characters as |
| Returns a Message object. |
| Deletes the response after a certain time (max 86400 seconds). |
| Deletes the trigger after a certain time (max 86400 seconds). |
| Deletes message with given |
| Adds each emoji as a reaction to the message that triggered the command (recognizes Unicode emojis and |
| Adds each emoji as a reaction to the response message (recognizes Unicode emojis and |
| Same as |
| Deletes all reactions pointed message has. |
Sends message to current channel
niland gets messageID to variable$x. Also adds reactions to this message. After 5 seconds, deletes that message. >{{ $x := sendMessageRetID nil "Hello there!" }} {{ addMessageReactions nil $x "👍" "👎" }} {{ deleteMessage nil $x 5 }}To demonstrate sleep and slightly also editMessage functions. >
{{ $x := sendMessageRetID nil "Hello" }} {{ sleep 3 }} {{ editMessage nil $x "There" }} {{ sleep 5 }} {{ sendMessage nil "We all know, that" }} {{ sleep 3 }} YAGPDB rules!
Function | Description |
| Mentions |
| Mentions |
| Mentions the first role found with the provided name (case-insensitive). |
| Mentions the role found with the provided ID. |
| Escapes everyone mentions in a string. |
| Escapes here mentions in a string. |
| Escapes everyone and here mentions in a string. Useful with sendMessageNoEscape, also applies to escapeEveryone/Here. Example in section's Snippets. |
<@{{ .User.ID }}>Outputs a mention to the user that called the command.<@###########>Mentions the user that has the ID ###### (See How to get IDs to get ID).<#&&&&&&&&&&&>Mentions the channel that has ID &&&&&& (See How to get IDs to get ID).<@&##########>Mentions the role with ID ######## (listroles command gives roleIDs). This is usable for example with{{ sendMessageNoEscape nil "Welcome to role <@&11111111...>" }}. Mentioning that role has to be enabled server- side in Discord.To demonstrate usage of escapeEveryoneHere. >
{{ $x := "@here Hello World! @everyone" }} {{ sendMessage nil $x }} {{ sendMessageNoEscape nil $x }} {{ sendMessageNoEscape nil (escapeEveryoneHere $x) }}
Function | Description |
| Returns true if the user has the role with the specified name (case-insensitive). |
| Returns true if the user has the role with the specified ID (use the listroles command for a list of roles). |
| Adds the role with the given ID to the user that triggered the command (use the listroles command for a list of roles). |
| Removes the role with the given ID from the user that triggered the command (use the listroles command for a list of roles). |
| Gives a role by ID to the target. |
| Gives a role by name to the target. |
| Takes away a role by ID from the target. |
| Takes away a role by name from the target. |
| Returns true if the given user has the role with the specified ID (use the listroles command for a list of roles). Example in section's Snippets. |
| Returns true if the given user has the role with the specified name (case-insensitive). |
To demonstrate usage of targetHasRoleID. >
{{ $x := (userArg (index .Args 1) ).ID }} {{ if targetHasRoleID $x ############ }} Has the Role! {{ else }} Does not have the role! {{ end }}
Function | Description |
| Returns value of type time and shows when the current user was created. |
| The account age of the current user in more human readable format
(Eg: |
| The account age of the current user in minutes. |
Function | Description |
| Returns a random adjective. |
| Iterates (loops) over the given slice or array and sets successive elements as active data (the dot) to be further handled inside the range template. Example usage here. More in-depth here. |
| Creates an unordered collection of key-value pairs, a dictionary so to say. The number of parameters to form key-value pairs must be even. |
| The same as |
| Creates a slice (similar to array) that can be used elsewhere ( |
| Function to generate embed inside custom command. More in-depth here. |
| Returns boolean true/false whether case-sensitive value is in list/slice. |
| Same as |
| Creates a new slice of type integer, beginning from start number, increasing in sequence and ending at stop (not included). |
| Returns a shuffled, randomized version of a list/slice. |
| Executes a YAGPDB command (e.g. reverse, roll, kick etc) in a custom command. Exec can be run max 5 times per command. If real command returns an embed - exec will return raw data of type embed, so you can use embed fields for better formatting - e.g. |
| Functions same way as |
| Checks the arguments for a specific type. More in depth here and an example in Custom Command Examples. |
| Defines type of argument for parseArgs. More in depth here and an example in Custom Command Examples. |
| Pauses execution of template inside custom command for max 60 seconds combined. Argument |
Function | Description |
| Function that executes another custom command specified by |
| Same as An example would be a mute command that schedules unmute in the future, but if you use the mute command again on the same user you dont want to schedule another unmute, you wanna overwrite the next unmute event to the new time, which is what this does. |
| Cancels a previously scheduled custom command execution using |
To demonstrates execCC and .ExecData using the same CC.
{{ $yag := "YAGPDB rules! " }}{{ $ctr := 0 }} {{ $yourCCID := toInt .CCID }}{{ if .ExecData }}{{ $ctr = add .ExecData.number 1 }}{{ $yag = joinStr "" $yag $ctr }} {{ .ExecData.YAGPDB }}{{ else }}So, someone rules.{{ $ctr = add $ctr 1 }} {{ $yag = joinStr "" $yag 1 }}{{ end }}{{ if lt $ctr 5 }}{{ execCC $yourCCID nil 10 (sdict "YAGPDB" $yag "number" $ctr) }}{{ else }} FUN'S OVER! {{ end }}
You have access to a basic set of Database functions, this is almost a key value store ordered by the key and value combined.
You can have max 50 * user_count (or 500 * user_count for premium) values in the database, if you go above this all new write functions will fail, this value is also cached so it won't be detected immediately when you go above nor immediately when you're under again.
Patterns are basic PostgreSQL patterns, not Regexp: An underscore (_) matches any single character; a percent sign (%) matches any sequence of zero or more characters.
Keys can be max 256 bytes long and has to be strings or numbers. Values can be anything, but if they go above 100KB they will be truncated.
You can just pass a userIDof 0 to make it global (or any other number, but 0 is safe).
There can be 10 database interactions per CC, out of which dbTop/BottomEntries, dbCount and dbGetPattern may be only run once (50,10 for premium users).
Example here.
Function | Description |
| Sets the value for the specified |
| Same as |
| Increments the value for specified key for the specified user, if there was no value then it will be set to |
| Retrieves a value from the database for the specified user, this returns DBEntry object. |
| Retrieves up to |
| Retrieves |
| Deletes the specified key for the specified value from the database. |
| Deletes database entry by it's ID. |
| Returns |
| Returns |
| Returns the count of all database entries which are not expired. Optional arguments: if |
Fields | Description |
| ID of the entry. |
| ID of the server. |
| ID of the user. |
| When this entry was created. |
| When this entry was last updated. |
| When entry will expire. |
| The key of the entry. |
| The value of the entry. |
Branching using if action's pipeline and comparison operators - these operators don't need to be inside if branch. if statements always need to have an enclosing end.
Case | Example |
if |
Initialization statement can also be inside |
else if |
You can have as many |
else |
|
not |
|
and |
|
or |
|
Equal: eq |
|
Not equal: ne |
|
Less than: lt |
|
Less than or equal: le |
|
Greater than: gt |
|
Greater than or equal: ge |
|
rangeiterates over element values in variety of data structures in pipeline - slices/arrays, maps or channels. The dot . is set to successive elements of those data structures and output will follow execution. If the value of pipeline has zero length, nothing is output or if an {{ else }} action is used, that section will be executed.
range on slices/arrays provides both the index and element for each entry; range on map iterates over key/element pairs. If a range action initializes a variable, that variable is set to the successive elements of the iteration. Range can also declare two variables, separated by a comma and set by index and element or key and element pair. In case of only one variable, it is assigned the element.
Like if, rangeis concluded with{{ end }}action and declared variable scope inside range extends to that point.
{{/* range over a slice */}}{{ range $index, $element := cslice "YAGPDB" "IS COOL!" }}{{ $index }} : {{ $element }} {{ end }}{{/* range on a map */}}{{ range $key, $value := dict "SO" "SAY" "WE" "ALL!" }}{{ $key }} : {{ $value }} {{ end }}{{/* range with else and variable scope */}}{{ range seq 1 1 }} no output {{ else }} output here {{ end }}{{ $x := 42 }} {{ range $x := seq 2 4 }} {{ $x }} {{ end }} {{ $x }}
with lets you assign and carry pipeline value with its type as a dot . inside that control structure, it's like a shorthand. If the value of the pipeline is empty, dot is unaffected and when {{ else }} is used, that branch is executed instead.
Affected dot inside with is important because methods mentioned above in this documentation:.Server.ID, .Message.Content etc are all already using the dot on the pipeline and if they are not carried over to the with control structure, these fields do not exists and template will error out.
Like if and range actions, with is concluded using {{ end }} and variable scope extends to that point.
{{/* Shows the scope and how dot is affected by object's value in pipeline */}}{{ $x := "42" }} {{ with and ($z:= seq 0 5) ($x := seq 0 10) }}len $x: `{{ len $x }}`same as len dot: `{{ len . }}` {{/* "and" function uses $x as last value for dot */}}but len $z is `{{ len $z }}` {{ end }}Outer-scope $x len however: {{ len $x }}{{/* when there's no value, dot is unaffected */}}{{ with false }} dot is unaffected {{ else }} printing here {{ .CCID }} {{ end }}
{{ if hasRoleName "funrole" }} Has role funrole {{ end }}This will only respond if the member has a role with name "funrole" .{{ if gt (len .Args) 0 }} {{ index .Args 1 }} {{ end }}Assuming your trigger is a command, will display your first input if input was given.{{ if eq .Channel.ID ####### }} YAG! {{ end }}Will only showYAG!if ChannelID is #####.{{ if ne .User.ID ####### }} YAG! {{ end }}Will ignore if user ID equal to ##### uses command.{{ addReactions .CmdArgs }}Adds the emoji following a trigger as reactions.{{ $a := (exec "catfact") }}Saves the response of thecatfactcommand to variable$a.{{ $allArgs := (joinStr " " .CmdArgs) }}Saves all the arguments after trigger to a variable$allArgs.{{/* this is a comment */}}For commenting something inside a template, use this syntax.To demonstrate usage of sdict methods .Get .Set .Del. >
{{ $x := sdict "key" "value" }} {{ $x.Get "key" }} {{ $x.Set "key" "eulav" }} {{ $x.Get "key" }} {{ $x.Del "key" }}to add to thatsdict, simply use.Setagain >{{ $x.Set "YAGPDB" "is cool!" }} {{ $x }}To demonstrate sleep and slightly also editMessage functions. >
{{ $x := sendMessageRetID nil "Hello" }} {{ sleep 3 }} {{ editMessage nil $x "There" }} {{ sleep 5 }} {{ sendMessage nil "We all know, that" }} {{ sleep 3 }} YAGPDB rules!
User IDs: Can be found by mentioning the user then adding a \ such as \@jonas747#0001 . Alternatively if you have developer mode on, you can right click and select Copy ID. How to enable developer mode in Discord.
Channel IDs: Can be found by mentioning the channel then adding a \ such as \#announcements. Alternatively if you have developer mode on, you can right click on the channel and select Copy ID.
Role IDs: Use the listrolescommand.
Emote IDs:
If it is a custom emote, adding a \ in front of the emote such as \:yag: will display the name along with the ID such as <:yag:277569741932068864>.
If it is an animated emote, do the same steps as a normal emote. If you do not have Discord Nitro, you can have a friend or a bot use the emote and right click on the emote to open its link. The ID will be a part of the URL.
If it is a default emote, look up the Unicode for the emote on Google. Note that some of the more customized default emotes such as some of the family emotes will not work in any of the YAGPDB commands.
