Home
“Documentation is for users.” // Rob Pike
All available data that can be used in PAGSTDB’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, index, len,etc > https://golang.org/pkg/text/template/ . This section is meant to be a concise and to the point reference document for all available templates/functions. Functions are covered here. For detailed explanations and syntax guide refer to the learning resource.
Legend: at current state this is still prone to formatting errors, but everything in a code block should refer to a function, parts of a template’s action-structure or output returned by PAGSTDB; single word/literal-structure in italics refers to type. Methods and fields (e.g. .Append, .User) are usually kept in standard formatting. If argument for a function is optional, it’s enclosed in parenthesis ( ). If there are many optional arguments possible, it’s usually denoted by 3-dot …ellipsis. If functions or methods are denoted with an accent, tilde ~, they are not yet deployed in actual PAGSTDB bot but are already in master code branch.
Always put curly brackets around the data and “actions you perform” you want to formulate as a template like this: {{.User.Username}}
This {{ ... }} syntax of having two curly brackets aka braces around context is necessary to form a template’s control structure also known as an action with methods and functions stated below.
NB! 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.
The dot (also known as cursor) {{ . }} encompasses all active data available for use in the templating system, in other words it always refers to current context.
For example .User is a Discord User object/structure of current context, meaning the triggering user. To get user object for other users, functions getMember, userArg would help. Same meaning of object/struct applies to other Fields with dot prefix. If it is mentioned as a Method (for example, .Append for type cslice) or as a field on a struct (for example, .User.Bot) then it can not be used alone in template context and always belongs on a parent value. That is, {{.Bot}} would return <no value> whereas {{.User.Bot}} returns bool true/false. Another good example is .Reaction.Emoji.MessageFormat, here you can use .MessageFormat every time you get emoji structure of type discordgo.Emoji, either using reaction triggers or for example .Guild.Emojis.
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.
For commenting something inside a template, use this syntax: {{\* this is a comment *\}}. May contain newlines. Comments do not nest and they start and end at the delimiters.
To trim spaces use hyphens after/before curyl brackets, for example > {{- \* this is a multi-line
comment with whitespace trimmed from preceding and following text *\ -}}
Using {{- ... -}} is also handy inside range actions, because whitespaces and newlines are rendered there as output.
$ has a special significance in templates, it is set to the starting value of a dot. This means you have access to the global context from anywhere - e.g., inside range/with actions. $ for global context would cease to work if you redefine it inside template, to recover it {{ $ := . }}.
$ also denotes the beginning of a variable, which maybe be initialized inside a template action. So data passed around template pipeline can be initialized using syntax > $variable := value. Previously declared variable can also be assigned with new data > $variable = value, it has to have a white-space before it or control panel will error out. Variable scope extends to the end action of the control structure (if, with, range, etc.) in which it is declared, or to the end of custom command if there are no control structures - call it global scope.
A powerful component of templates is the ability to stack actions - like function calls, together - chaining one after another. This is done by using pipes |. Borrowed from Unix pipes, the concept is simple: each pipeline’s output becomes the input of the following pipe. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
Example: {{randInt 41 | add 2}} would pipelinerandInt function’s return to addition add as second parameter and it would be added to 2; this more simplified would be like {{40 | add 2}} with return 42. If written normally, it would be {{ add 2 (randInt 41) }}. Same pipeline but using a variable is also useful one > {{$x:=40 | add 2}} would not return anything as printout, 40 still goes through pipeline to addition and 42 is stored to variable $x whereas {{($x:=40) | add 2}} would return 42 and store 40 to $x.
NB! Pipes are useful in select cases to shorten code and in some cases improve readability, but they should not be overused. In most cases, pipes are unnecessary and cause a dip in readability that helps nobody.