| Function | Description |
|---|---|
| **Function** | **Description** |
| `adjective` | Returns a random adjective. |
| `cembed` "list of embed values" | Function to generate embed inside custom command. [More in-depth here](/reference/custom-embeds). |
| `createTicket` author topic | Creates a new ticket with the author and topic provided. Covered in its own section [here](/reference/templates#tickets). |
| `cslice`, `sdict` | These functions are covered in their own section [here](/reference/templates#custom-types). |
| `dict` key1 value1 key2 value2 ... | 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. Example [here](/reference/custom-command-examples#dictionary-example). Keys and values can be of any type. Key is not restricted to _string_ only as in case with `sdict`. `dict` also has helper methods .Del, .Get, .HasKey and .Set and they function the same way as `sdict` ones discussed [here](/reference/templates#templates.Sdict). |
| `exec` "command" "args" "args" "args" ... | Executes a YAGPDB command (e.g. roll, kick etc) in a custom command. Exec can be run max 5 times per CC. 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. `{{$resp := exec "whois"}} {{$resp.Title}} Joined at > {{(index $resp.Fields 4).Value}}` will return the title (username#discriminator) and "Joined at" field's value from `whois` command. **NB!** This will not work for commands with paginated embed returns, like `un/nn` commands!exec syntax is `exec "command" arguments` - this means you format it the same way as you would type the command regularly, just without the prefix, e.g. if you want to clear 2 messages and avoiding the pinned message > `{{exec "clear 2 -nopin"}}`, where `"command"` part is whole `"clear 2 -nopin"`. If you change that number inside CC somewhere then you have to use `arguments` part of exec formatting > `{{$x := 2}} {{exec "clear" $x "-nopin"}}` Here `"clear"` is the `"command"` and it is followed by `arguments`, one variable `$x` and one string `"-nopin"`. Last example is the same as `{{exec (joinStr " " "clear" $x "-nopin")}}`(also notice the space in `joinStr` separator). |
| `execAdmin` "command" "args" "args" "args" ... | Functions same way as `exec` but effectively runs the command as the bot user (YAGPDB). This has essentially the same effect as if a user with the same permissions and roles as YAGPDB ran the command: for example, if YAGPDB had ban members permission but the user which ran the command did not, `{{exec "ban" 12345}}` would error due to insufficient permissions but `{{execAdmin "ban" 12345}}` would succeed. |
| `execTemplate` "template" data | Executes the associated template, optionally with data. A more detailed treatment of this function can be found in the [Associated Templates](/reference/templates#associated-templates) section. |
| `getWarnings` user | Returns a _slice_ of warnings of type _[[]*moderation.WarningModel](https://github.com/botlabs-gg/yagpdb/blob/master/moderation/models.go#L121)_ given to user argument which can be its ID or user object. |
| `hasPrefix` string prefix | `hasPrefix` tests whether the given `string` begins with `prefix` and returns _bool_. Example > `{{hasPrefix "YAGPDB" "YAG"}}` returns `true`. |
| `hasSuffix` string suffix | hasSuffix tests whether the given `string` ends with `suffix` and returns _bool_.Example > `{{hasSuffix "YAGPDB" "YAG"}}` returns `false`. |
| `humanizeThousands` arg | This function places comma to separate groups of thousands of a number. `arg` can be _int_ or _string_, has to be a whole number, e.g. `{{humanizeThousands "1234567890"}}` will return `1,234,567,890`. |
| `in` list value | Returns _bool_ true/false whether case-sensitive value is in list/_slice_. `{{ in (cslice "YAGPDB" "is cool") "yagpdb" }}` returns `false`. |
| `index` arg ...keys | Returns the result by indexing its first argument with following arguments. Each indexed item must be a _map_, _slice_ or _array._ Indexed _string_ returns value in _uint8._ Example: `{{index .Args 1}}` returns first argument after trigger which is always at position 0. More than one positional keys can be used, in pseudo-code: `index X 0 1` is equivalent to calling `index (index X 0) 1` |
| `inFold` list value | Same as `in`, but is case-insensitive. `{{inFold (cslice "YAGPDB" "is cool") "yagpdb"}}` returns `true`. |
| `kindOf` value (flag) | This function helps to determine what kind of data type we are dealing with. `flag` part is a _bool_ and if set as **true** (**false** is optional) returns the value where given `value` points to. Example: `{{kindOf cembed false}} {{kindOf cembed true}}` will return `ptr` and `struct`. |
| `len` arg | Returns the integer length of its argument. arg can be an _array_, _slice_, _map_, or _string._`{{ len (cslice 1 2 3) }}`returns `3`. |
| `noun` | Returns a random noun. |
| `parseArgs` required_args error_message `...carg` | Checks the arguments for a specific type. Has methods `.Get` and `.IsSet`. `carg "type" "name"` is required by `parseArgs` and it defines the type of argument for `parseArgs`. An example in [Custom Command Examples.](/reference/custom-command-examples.md#parseargs-example) |
| `sendTemplate` channel templateName (data) | Function sends a formulated template to another channel and returns sent response's messageID. Channel is like always either name, number or nil; and returns messageID. `data` is optional and is meant for additional data for the template.Example: `{{define "logsTemplate"}}This text will output on different channel, you can also use functions like {{currentTime}}. {{.TemplateArgs}} would be additional data sent out. {{end}}`Now we call that "logs" in the same custom command.`{{sendTemplate "logs" "logsTemplate" "YAG rules!"}}.` Template definitions are discussed [here](https://pkg.go.dev/text/template#hdr-Nested_template_definitions). |
| `sendTemplateDM` templateName (data) | Works the same way as function above. Only channel's name is not in the arguments. YAGPDB **will only** DM the triggering user. This function will not work for leave messages. |
| `seq` start stop | Creates a new _slice_ of type _int_, beginning from start number, increasing in sequence and ending at stop (not included). `{{seq -4 2}}` returns a _slice_ `[ -4 -3 -2 -1 0 1 ]`. Sequence's max length is 10 000. |
| `shuffle` list | Returns a shuffled, randomized version of a list/_slice_. |
| `sleep` seconds | Pauses execution of template's action-structure inside custom command for max 60 seconds combined. Argument`seconds`is an integer (whole number). Example in [snippets](#message-sections-snippets). |
| `sort` slice (...args) | Sorts a slice of same type values with optional arguments. These arguments are presented in an `sdict` as keys: `"reverse"` true/false and `"key"` with dictionary/map's key name as value.Example > `{{sort (cslice (sdict "name" "bob") (sdict "name" "alice") (sdict "name" "yagpdb")) (sdict "key" "name" "reverse" true)}}` would return `[map[name:yagpdb] map[name:bob] map[name:alice]]`.Sorting mixed types is not supported. Previous sorting options `"subslices"` and `"emptyslices"` have been removed. Sort function is limited to 1/3 CC calls regular/premium. |
| `verb` | Returns a random verb. |
| Function | Description |
|---|---|
| **Function** | **Description** |
| `adjective` | Returns a random adjective. |
| `cembed` "list of embed values" | Function to generate embed inside custom command. [In-depth custom embeds reference](/reference/custom-embeds). |
| `createTicket` author topic | Creates a new ticket with the author and topic provided. [Ticket object documentation](/reference/templates#tickets). |
| `cslice`, `sdict` | Please see [custom type documentation](/reference/templates#custom-types). |
| `dict` key1 value1 key2 value2 ... | 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. [Dictionary example script](/reference/custom-command-examples#dictionary-example). Keys and values can be of any type. Key is not restricted to _string_ only as in case with `sdict`. `dict` also has helper methods .Del, .Get, .HasKey and .Set and they function the same way as `sdict` ones discussed in [templates.Sdict documentation](/reference/templates#templates.Sdict). |
| `exec` "command" "args" "args" "args" ... | Executes a YAGPDB command (e.g. roll, kick etc) in a custom command. Exec can be run max 5 times per CC. 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. `{{$resp := exec "whois"}} {{$resp.Title}} Joined at > {{(index $resp.Fields 4).Value}}` will return the title (username#discriminator) and "Joined at" field's value from `whois` command. **NB!** This will not work for commands with paginated embed returns, like `un/nn` commands!exec syntax is `exec "command" arguments` - this means you format it the same way as you would type the command regularly, just without the prefix, e.g. if you want to clear 2 messages and avoiding the pinned message > `{{exec "clear 2 -nopin"}}`, where `"command"` part is whole `"clear 2 -nopin"`. If you change that number inside CC somewhere then you have to use `arguments` part of exec formatting > `{{$x := 2}} {{exec "clear" $x "-nopin"}}` Here `"clear"` is the `"command"` and it is followed by `arguments`, one variable `$x` and one string `"-nopin"`. Last example is the same as `{{exec (joinStr " " "clear" $x "-nopin")}}`(also notice the space in `joinStr` separator). |
| `execAdmin` "command" "args" "args" "args" ... | Functions same way as `exec` but effectively runs the command as the bot user (YAGPDB). This has essentially the same effect as if a user with the same permissions and roles as YAGPDB ran the command: for example, if YAGPDB had ban members permission but the user which ran the command did not, `{{exec "ban" 12345}}` would error due to insufficient permissions but `{{execAdmin "ban" 12345}}` would succeed. |
| `execTemplate` "template" data | Executes the associated template, optionally with data. A more detailed treatment of this function can be found in the [Associated Templates](/reference/templates#associated-templates) section. |
| `getWarnings` user | Returns a _slice_ of warnings of type _[[]*moderation.WarningModel](https://github.com/botlabs-gg/yagpdb/blob/master/moderation/models.go#L121)_ given to user argument which can be its ID or user object. |
| `hasPrefix` string prefix | `hasPrefix` tests whether the given `string` begins with `prefix` and returns _bool_. Example > `{{hasPrefix "YAGPDB" "YAG"}}` returns `true`. |
| `hasSuffix` string suffix | hasSuffix tests whether the given `string` ends with `suffix` and returns _bool_.Example > `{{hasSuffix "YAGPDB" "YAG"}}` returns `false`. |
| `humanizeThousands` arg | This function places comma to separate groups of thousands of a number. `arg` can be _int_ or _string_, has to be a whole number, e.g. `{{humanizeThousands "1234567890"}}` will return `1,234,567,890`. |
| `in` list value | Returns _bool_ true/false whether case-sensitive value is in list/_slice_. `{{ in (cslice "YAGPDB" "is cool") "yagpdb" }}` returns `false`. |
| `index` arg ...keys | Returns the result by indexing its first argument with following arguments. Each indexed item must be a _map_, _slice_ or _array._ Indexed _string_ returns value in _uint8._ Example: `{{index .Args 1}}` returns first argument after trigger which is always at position 0. More than one positional keys can be used, in pseudo-code: `index X 0 1` is equivalent to calling `index (index X 0) 1` |
| `inFold` list value | Same as `in`, but is case-insensitive. `{{inFold (cslice "YAGPDB" "is cool") "yagpdb"}}` returns `true`. |
| `kindOf` value (flag) | This function helps to determine what kind of data type we are dealing with. `flag` part is a _bool_ and if set as **true** (**false** is optional) returns the value where given `value` points to. Example: `{{kindOf cembed false}} {{kindOf cembed true}}` will return `ptr` and `struct`. |
| `len` arg | Returns the integer length of its argument. arg can be an _array_, _slice_, _map_, or _string._`{{ len (cslice 1 2 3) }}`returns `3`. |
| `noun` | Returns a random noun. |
| `parseArgs` required_args error_message `...carg` | Checks the arguments for a specific type. Has methods `.Get` and `.IsSet`. `carg "type" "name"` is required by `parseArgs` and it defines the type of argument for `parseArgs`. An example in [Custom Command Examples.](/reference/custom-command-examples.md#parseargs-example) |
| `sendTemplate` channel templateName (data) | Function sends a formulated template to another channel and returns sent response's messageID. Channel is like always either name, number or nil; and returns messageID. `data` is optional and is meant for additional data for the template.Example: `{{define "logsTemplate"}}This text will output on different channel, you can also use functions like {{currentTime}}. {{.TemplateArgs}} would be additional data sent out. {{end}}`Now we call that "logs" in the same custom command.`{{sendTemplate "logs" "logsTemplate" "YAG rules!"}}.` [Template definition documentation](https://pkg.go.dev/text/template#hdr-Nested_template_definitions). |
| `sendTemplateDM` templateName (data) | Works the same way as function above. Only channel's name is not in the arguments. YAGPDB **will only** DM the triggering user. This function will not work for leave messages. |
| `seq` start stop | Creates a new _slice_ of type _int_, beginning from start number, increasing in sequence and ending at stop (not included). `{{seq -4 2}}` returns a _slice_ `[ -4 -3 -2 -1 0 1 ]`. Sequence's max length is 10 000. |
| `shuffle` list | Returns a shuffled, randomized version of a list/_slice_. |
| `sleep` seconds | Pauses execution of template's action-structure inside custom command for max 60 seconds combined. Argument`seconds`is an integer (whole number). Example in [snippets](#message-sections-snippets). |
| `sort` slice (...args) | Sorts a slice of same type values with optional arguments. These arguments are presented in an `sdict` as keys: `"reverse"` true/false and `"key"` with dictionary/map's key name as value.Example > `{{sort (cslice (sdict "name" "bob") (sdict "name" "alice") (sdict "name" "yagpdb")) (sdict "key" "name" "reverse" true)}}` would return `[map[name:yagpdb] map[name:bob] map[name:alice]]`.Sorting mixed types is not supported. Previous sorting options `"subslices"` and `"emptyslices"` have been removed. Sort function is limited to 1/3 CC calls regular/premium. |
| `verb` | Returns a random verb. |
| Function | Description |
|---|---|
| **Function** | **Description** |
| `json` value (flag) | Traverses given `value` through MarshalJSON ([more here](https://golang.org/pkg/encoding/json/#Marshal)) and returns it as type _string_. For example `{{json .TimeHour}}` outputs type _string_; before this `.TimeHour` was of type _time.Duration_. Basically it's good to use if multistep type conversion is needed `(toString (toInt value) )` and certain parts of `cembed` need this for example. `flag` part is a _bool_ and if set as **true** (**false** is optional) returns the value indented through MarshalIndent. |
| `jsonToSdict` value | Returns `templates.SDict` from given JSON argument, e.g. `{{jsonToSdict `{"yagpdb":"is cool"}` }}` would print `map[yagpdb:is cool]`. |
| `structToSdict` struct | Function converts exported field-value pairs of a _struct_ to an _sdict_. For example it is useful for editing embeds, rather than having to reconstruct the embed field by field manually. Example: `{{$x := cembed "title" "Something rules!" "color" 0x89aa00}} {{$x.Title}} {{$x = structToSdict $x}} {{- $x.Set "Title" "No, YAGPDB rules!!!" -}} {{$x.Title}} {{$x}}` will return No, YAGPDB rules!!! and whole sdict-mapped _cembed_. |
| `toByte` "arg" | Function converts input to a slice of bytes - meaning _[]uint8_. `{{toByte "YAG€"}}` would output `[89 65 71 226 130 172]`. `toString` is capable of converting that slice back to _string_. |
| `toDuration` | Converts the argument, number or string to type _time.Duration_ - more duration related methods [here](https://pkg.go.dev/time#Duration). Number represents nanoseconds. String can be with time modifier (second, minute, hour, day etc) `s, m, h, d, w, mo, y`,without a modifier string will be converted to minutes. Usage:`(toDuration x)`. Example in section's [Snippets](#type-conversion-sections-snippets). |
| `toFloat` | Converts argument (_int_ or _string_ type of a number) to type _float64_. Usage: `(toFloat x)`. Function will return 0, if type can't be converted to _float64_. |
| `toInt` | Converts something into an integer of type _int_. Usage: `(toInt x)`. Function will return 0, if type can't be converted to _int._ |
| `toInt64` | Converts something into an _int64_. Usage: `(toInt64 x)`. Function will return 0, if type can't be converted to _int64._ |
| `toRune` "arg" | Function converts input to a slice of runes - meaning _[]int32_. `{{toRune "YAG€"}}`would output `[89 65 71 8364]`. These two functions - the one above, are good for further analysis of Unicode strings. `toString` is capable of converting that slice back to _string_. |
| `toString` | Has alias `str`. Converts some other types into a _string_. Usage: `(toString x)`. |
| Function | Description |
|---|---|
| **Function** | **Description** |
| `json` value (flag) | Traverses given `value` through MarshalJSON (see [Golang json documentation](https://golang.org/pkg/encoding/json/#Marshal)) and returns it as type _string_. For example `{{json .TimeHour}}` outputs type _string_; before this `.TimeHour` was of type _time.Duration_. Basically it's good to use if multistep type conversion is needed `(toString (toInt value) )` and certain parts of `cembed` need this for example. `flag` part is a _bool_ and if set as **true** (**false** is optional) returns the value indented through MarshalIndent. |
| `jsonToSdict` value | Returns `templates.SDict` from given JSON argument, e.g. `{{jsonToSdict `{"yagpdb":"is cool"}` }}` would print `map[yagpdb:is cool]`. |
| `structToSdict` struct | Function converts exported field-value pairs of a _struct_ to an _sdict_. For example it is useful for editing embeds, rather than having to reconstruct the embed field by field manually. Example: `{{$x := cembed "title" "Something rules!" "color" 0x89aa00}} {{$x.Title}} {{$x = structToSdict $x}} {{- $x.Set "Title" "No, YAGPDB rules!!!" -}} {{$x.Title}} {{$x}}` will return No, YAGPDB rules!!! and whole sdict-mapped _cembed_. |
| `toByte` "arg" | Function converts input to a slice of bytes - meaning _[]uint8_. `{{toByte "YAG€"}}` would output `[89 65 71 226 130 172]`. `toString` is capable of converting that slice back to _string_. |
| `toDuration` | Converts the argument, number or string to type _time.Duration_ - more duration related methods in [Golang time documentation](https://pkg.go.dev/time#Duration). Number represents nanoseconds. String can be with time modifier (second, minute, hour, day etc) `s, m, h, d, w, mo, y`,without a modifier string will be converted to minutes. Usage:`(toDuration x)`. Example in section's [Snippets](#type-conversion-sections-snippets). |
| `toFloat` | Converts argument (_int_ or _string_ type of a number) to type _float64_. Usage: `(toFloat x)`. Function will return 0, if type can't be converted to _float64_. |
| `toInt` | Converts something into an integer of type _int_. Usage: `(toInt x)`. Function will return 0, if type can't be converted to _int._ |
| `toInt64` | Converts something into an _int64_. Usage: `(toInt64 x)`. Function will return 0, if type can't be converted to _int64._ |
| `toRune` "arg" | Function converts input to a slice of runes - meaning _[]int32_. `{{toRune "YAG€"}}`would output `[89 65 71 8364]`. These two functions - the one above, are good for further analysis of Unicode strings. `toString` is capable of converting that slice back to _string_. |
| `toString` | Has alias `str`. Converts some other types into a _string_. Usage: `(toString x)`. |