diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..3233403 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "databsase" + ] +} diff --git a/content/custom-commands/commands.md b/content/custom-commands/commands.md index 2a178b9..da2180c 100644 --- a/content/custom-commands/commands.md +++ b/content/custom-commands/commands.md @@ -3,7 +3,8 @@ title = 'Commands' weight = 1 +++ -The commands page displays all custom commands and allows you to add, delete, or edit custom commands and custom command groups. +The commands page displays all custom commands and allows you to add, delete, or edit custom commands and custom command +groups. @@ -11,13 +12,16 @@ The commands page displays all custom commands and allows you to add, delete, or
-**1** Create Custom Command button **2** List of commands in the selected group **3** Edit this Custom Command **4** Delete this custom command **5** Run this Interval Commandnow **6** Selected group **7** Group tabs **8** Name of selected group **9** Delete selected group **10** Channel and Role Restrictions **11** Save group settings +**1** Create Custom Command **2** List of Commands in Selected Group **3** Edit this Custom Command **4** Delete this +Custom Command **5** Run this Command Now **6** Selected Group **7** Group Tabs **8** Name of Selected Group **9** +Delete Selected Group **10** Channel and Role Restrictions **11** Save group settings
## Creating a Custom Command -Clicking the Create a new Custom Command button (**1**) will instantly create a new command within the selected group (**6**) then redirect you to the edit page for the new CC. +Clicking the Create Custom Command (**1**) will instantly create a new command within the selected group (**6**) then +redirect you to the page to edit it. A new custom command has the default response: @@ -25,13 +29,14 @@ A new custom command has the default response: Edit this to change the output of the custom command {{.CCID}}! ``` -It also assigns the command an ID determined by the number of commands you have created. +It also assigns the command an ID determined by the number of commands you have created in the guild. {{% notice style="tip" title="Troubleshooting" %}} ![Empty CC Discord Messages](empty_cc_1.png) -If the bot is sending messages such as this in your server, you are likely accidentally triggering CCs with the default response. Check the commands page to find any CCs with empty responses. +If the bot is sending messages such as this in your server, you are likely accidentally triggering CCs with the default +response. Check the commands page to find any CCs with empty responses. ![An empty CC on the dashboard](empty_cc_2.png) @@ -39,21 +44,27 @@ If the bot is sending messages such as this in your server, you are likely accid ## Command List -The commands page lists the commands (**2**) in the selected group (**6**). They are ordered by [ID](#id-and-name) and display their name (if set), [trigger type](#trigger-types), and trigger (if applicable). You can expand the command by clicking the down arrow, allowing you to preview the full, syntax-highlighted command response. +The commands page lists the commands (**2**) in the selected group (**6**). They are ordered by [ID](#id-and-name) and +display their name (if set), [trigger type](#trigger-types), and trigger text (if applicable). You can expand the +command by clicking on it, allowing you to preview the full, syntax-highlighted command response. -### Delete Command Button +### Delete a Command Deleting a custom command (**4**) will **permanently** delete the command after confirmation. This cannot be undone. ### Run Now -The Run now button (**5**) appears on [Interval trigger](#hourlyminute-interval) commands. It executes the command and resets the next run time based off the current time. +The Run now button (**5**) appears on [Interval trigger](#hourlyminute-interval) commands. It executes the command as +long as it isn't disabled and a channel is selected, and redirects you to the edit command page for the command. + +Manually running an interval command reschedules all subsequent runs based off the current time. ## Command Groups Command groups allow you to organize your custom commands and apply role and channel restrictions to multiple commands. -The group tabs at the top of the page (**7**) allow you to switch to any of your created groups. The **+** button allows you to create a new group. +The group tabs at the top of the page (**7**) allow you to switch to any of your created groups. The **+** button allows +you to create a new group. ### Editing a Group @@ -66,11 +77,11 @@ Selecting a group allows you to edit it. Any changes must be saved (**11**) to t #### Role/Channel Restrictions -Restricting a custom command (**10**) prevents it from triggering when not permitted to. A user who tries to run a custom command with the wrong roles/in the wrong channel will not trigger the response or an error. - -Whitelisting roles or channels causes them to be required to run the command. +Restricting a custom command (**10**) adds conditions for it to run A user who tries to run a custom command with the +wrong roles/in the wrong channel will not trigger the response or an error. -Blacklisted roles or channels will not be permitted to run the command. +- Whitelisting roles or channels causes them to be required to run the command. +- Blacklisted roles or channels will not be permitted to run the command. {{% notice style="note" %}} @@ -88,7 +99,10 @@ Editing a custom command (**3**) opens up a separate page for configuration.
-**1** ID **2** Name **3** Trigger type **4** Trigger text **5** Case sensitivity toggle **6** Message edits trigger toggle **7** Response **8** Add response **9** Custom command group selection **10** Channel and Role Restrictions **11** Execution statistics **12** Error output toggle **13** Enable command toggle **14** Save command button **15** Delete command button +**1** ID **2** Name **3** Trigger Type **4** Trigger Text **5** Case Sensitivity Toggle **6** Message Edits Trigger +Toggle **7** Response **8** Add Response **9** Custom Command Group **10** Channel and Role Restrictions +**11** Execution Statistics **12** Error Output Toggle **13** Enable Command Toggle **14** Save Command **15** +Delete command button
@@ -96,9 +110,13 @@ Editing a custom command (**3**) opens up a separate page for configuration. Custom Commands are identified by either their ID or their name. -When a custom command is created, the system assigns it a numeric **ID** (**1**) starting at `1`. The number increases with each custom command created on your server. It is not based on the _current_ number of custom commands, but the total commands that have ever been created on the server. This ID is permanent, and cannot be changed or re-ordered. +When a custom command is created, the system assigns it a numeric **ID** (**1**) starting at `1`. The number increases +with each custom command created on your server. It is not based on the _current_ number of custom commands, but the +total commands that have ever been created on the server. This ID is permanent, and cannot be changed or re-ordered. -The ID may be used to identify a CC for a variety of functions. Calling `.CCID` within a command response will return this ID. You must target a CC ID for `execCC`. You can use run the `CustomCommands` command with a CC ID to retrive info about that CC. +The ID may be used to identify a CC for a variety of purposes. Calling `{{ .CCID }}` within a command response will +return its ID. You must target a CC ID for `execCC`. You can use run the `CustomCommands` command with a CC ID to +retrieve info about that CC. {{% notice warning %}} @@ -106,17 +124,21 @@ Deleting a Custom Command does not allow its ID to be reassigned. If you delete {{% /notice %}} -A Custom Command's **name** (**2**), conversely, is defined by the user. It is an optional argument that can be used to identify the command in the control panel and with the `CustomCommands` command. It has a 100 character limit on length. +A Custom Command's **name** (**2**), conversely, is defined by the user. It is an optional argument that can be used to +identify the command in the control panel and with the `CustomCommands` command. Max 100 characters. ### Triggers -A trigger (**3**) defines what runs the command. Depending on the type of trigger you may also need to specify additional configuration. For example, most trigger types require a **Trigger** (**4**) field defining the text the command should match against new messages. +A trigger (**3**) defines what runs the command. Depending on the type of trigger you may also need to specify +additional configuration. For example, most trigger types require a **Trigger** (**4**) field defining the text the +command should match against new messages. Max 1000 characters. #### Trigger types ##### Command -Messages **starting with the prefix** for your server (- by default) _OR_ by mentioning the bot followed by the trigger text (**4**) will trigger the command. +Messages **starting with the prefix** for your server (- by default) _OR_ by mentioning the bot followed by the trigger +text (**4**) will trigger the command. ###### Example @@ -159,7 +181,8 @@ Can specify **Added Only**, **Removed Only**, or **Both** to restrict which type {{% notice style="tip" title="Filtering Emojis" %}} -You cannot specify which emojis the command will trigger on. If you'd like to limit which emojis run the code, you will need to write that code yourself in the response. +You cannot specify which emojis the command will trigger on. If you'd like to limit which emojis run the code, you will +need to write that code yourself in the response. Example: @@ -177,7 +200,8 @@ Example: Interval triggers will run the command at a set interval in the selected channel. -The Member in context is nil, and functions relying on the Member context will fail. However, `exec` will still run commands as the bot. +The Member in context is nil, and functions relying on the Member context will fail. However, `exec` will run commands +as the bot. ![Overview of interval configuration options.](interval_trigger_options.png?width=60vw) @@ -191,9 +215,13 @@ Interval (**1**) sets how often the command will run in **hours** or **minutes** Channel (**2**) specifies a channel to run the command in. The response will be sent to this channel. -Excluding hours and/or weekdays (**3**) prevents the command from triggering during those hours or weekdays. **This uses UTC time**, not your local timezone. +Excluding hours and/or weekdays (**3**) prevents the command from triggering during those hours or weekdays. **This uses +UTC time**, not your local timezone. + +When editing an interval command, a **Run Now** button appears at the bottom of the page. It executes the command as +long as it isn't disabled and a channel is selected. -When editing an interval command, a **Run now** button appears at the bottom of the page. Clicking this executes the command and resets the next run time based off the current time. +Manually running an interval command reschedules all subsequent runs based off the current time. {{% notice info %}} @@ -203,13 +231,17 @@ You must specify a channel to run interval commands in even if the command doesn #### Case Sensitivity -Any commands which allow you to specify trigger text (ex. Command, Regex, Exact match, etc.) have a **Case sensitive** toggle (**5**) which is off by default. A case sensitive trigger `yagPDB` will trigger on "yagPDB" but not "yagpdb" or "YAGPDB". +Any commands which allow you to specify trigger text (ex. Command, Regex, Exact match, etc.) have a **Case sensitivity** +toggle (**5**) which is off by default. A case sensitive trigger `yagPDB` will trigger on "yagPDB" but not "yagpdb" or +"YAGPDB". #### Edit Message Trigger -Commands which trigger on messages have a **Trigger on message edits** toggle (**6**) which is off by default. If a message is edited and matches the trigger text just like a message would, it will trigger the command. +Commands which trigger on messages have a **Trigger on message edits** toggle (**6**) which is off by default. If a +message is edited and matches the trigger text, it will trigger the command. -The edited message toggle is an _additional_ trigger to the sent message trigger. If you'd like to _only_ trigger on message edits, you will need to conditional branch with `.IsMessageEdit`. +The edited message toggle is an _additional_ trigger to the sent message trigger. If you'd like to _only_ trigger on +message edits, you will need to conditional branch with `{{ .IsMessageEdit }}`. This feature is [premium only](/premium). @@ -217,15 +249,18 @@ This feature is [premium only](/premium). The response (**7**) defines the message the bot will send once the command is triggered. -Optionally define multiple responses which the bot will randomly select from when the command is run. Add a response with the plus button on the right of the response (**8**) +Optionally define multiple responses which the bot will randomly select from when the command is run. Add a response +with the plus button on the right of the response (**8**). -The response supports the custom template script, allowing for more complex functionality such as assigning roles, getting data from users, sending messages to other channels, and more. Visit the Templates reference page to learn more. +The response supports the custom template script, allowing for more complex functionality such as assigning roles, +getting data from users, sending messages to other channels, and more. Visit the Templates reference page to learn more. {{% button href="/reference/templates" style="transparent" %}}Templates{{% /button %}} {{% notice style="tip" title="Keeping your code safe" %}} -It is reccommended to save local copies of your custom commands. There is no way to recover deleted or overwritten CCs. Use an editor like **Vim**, **VS Code**, or **Notepad++** for the best coding experience. +It is recommended to save local copies of your custom commands. There is no way to recover deleted or overwritten CCs. +Use an editor like **Vim**, **VS Code**, or **Notepad++** for the best coding experience. {{% /notice %}} @@ -235,47 +270,49 @@ Dropdown selection (**9**) to change which command group the command is in. Sele ### Channel and Role Restrictions -Restricting a custom command (**10**) prevents it from triggering when not permitted to. A user who tries to run a custom command with the wrong roles/in the wrong channel will not trigger the response or an error. A dropdown selection allows you to select a list of roles or channels, and the checkbox allows you to define the list as a blacklist or a whitelist. +Restricting a custom command (**10**) adds conditions for it to run A user who tries to run a custom command with the +wrong roles/in the wrong channel will not trigger the response or an error. -#### Role Restrictions +A dropdown selection allows you to select a list of roles or channels, and the checkbox allows you to define the list as +a blacklist or a whitelist. + +- Whitelisting roles or channels causes them to be required to run the command. +- Blacklisted roles or channels will not be permitted to run the command. {{% notice info %}} -Role restrictions ignores user permissions. Having `Administrator` permissions will not override these restrictions. +Role restrictions are unrelated to user permissions. Having `Administrator` permissions will not override these +restrictions. {{% /notice %}} -**Require at least one of the roles** in the following list causes the command to ignore any user who does not have _at least one_ of the roles in the list. - -**Ignore the roles** in the following list causes the command to ignore any user who has _at least one_ of the roles in the list. - -#### Channel Restrictions - -**Only run** in the following channels causes the command to ignore the command if it's run outside of any of the selected channels. - -**Ignore the channels** in the following list causes the command to ignore the command when it's run in any of the selected channels. - -##### CC Groups +#### CC Groups -A user executing a command must pass both the overarching group's restrictions and the command restrictions. Command-specific restrictions will _not_ override the group restrictions. +A user executing a command must pass both the overarching group's restrictions and the command restrictions. +Command-specific whitelists will _not_ override the group restrictions. -#### Execution Statistics +### Execution Statistics -The execution statistics (**11**) show details about the custom command's executions. It's updated after the command runs. +The execution statistics (**11**) show details about the custom command's executions. It's updated after the command +runs. -##### Last Error +#### Last Error -The most recent error which occurred running the command, UTC Timestamped. The error display is not cleared when the command runs successfully. +The most recent error which occurred running the command, UTC Timestamped. The error display is not cleared when the +command runs successfully. -##### Run Count +#### Run Count -A count of how many times the command executed the response. This counter increases even if the command errors, or does not send a response. It also increases if the command is run via `execCC`. +A count of how many times the command executed the response. This counter increases even if the command errors, or does +not send a response. It also increases if the command is run via `execCC`. The run count will not increase if the user who ran the command did not pass the restrictions. {{% notice style="tip" title="Troubleshooting" %}} -If your command fails to run, check the run count. If the run count increases when you attempt to run the command, the issue is with your code. Otherwise, the issue may be with YAGPDB's permissions in your server, or incorrectly setup Role/Channel Restrictions in the command and/or command group. +If your command fails to run, check the run count. If the run count increases when you attempt to run the command, the +issue is with your code. Otherwise, the issue may be with YAGPDB's permissions in your server, or incorrectly setup +Role/Channel Restrictions in the command and/or command group. {{% /notice %}} @@ -289,15 +326,17 @@ Only shown on Interval type commands. A UTC Timestamp of the next time the comma ### Output errors as command response -This toggle (**12**) determines whether errors during command execution are sent in the command response after the command fails. Does not effect logging of Last error to the statistics. +This toggle (**12**) determines whether errors during command execution are sent in the command response after the +command fails. Does not effect logging of Last Error to the statistics. ### Command Enabled -This toggle (**13**) enables the command. A disabled command will never run (not even with `execCC`) or count against the trigger limit. +This toggle (**13**) enables the command. A disabled command will never run (not even with `execCC`) or count against +the trigger limit. ### Saving Your Command -Saving (**14**) the command updates it with the input values. +Saving (**14**) the command updates it with the new values if there are no errors. Alt + Shift + S also saves the custom command. @@ -311,7 +350,9 @@ If you save a command with an interval trigger which has never been run, it will {{% notice style="tip" title="Keeping your code safe" %}} -It is reccomended to code your custom command using a local editor on your device. You will not be able to save your code on the dashboard if there are syntax errors in your code. Use an editor like **Vim**, **VS Code**, or **Notepad++** for the best coding experience. +It is recommended to code your custom command using a local editor on your device. You will not be able to save your +code on the dashboard if there are syntax errors in your code. Use an editor like **Vim**, **VS Code**, or **Notepad++** +for the best coding experience. {{% /notice %}} @@ -321,6 +362,6 @@ Custom commands do not autosave. {{% /notice %}} -### Delete Command +### Delete Current Command -Deleting a custom command (**15**) will **permanently** delete the command after confirmation. This cannot be undone. +Deleting the custom command (**15**) will **permanently** delete the command after confirmation. This cannot be undone. diff --git a/content/custom-commands/database.md b/content/custom-commands/database.md index f6f919a..9580286 100644 --- a/content/custom-commands/database.md +++ b/content/custom-commands/database.md @@ -3,7 +3,8 @@ title = 'Database' weight = 2 +++ -The Custom Command Database is used for persistent storage between custom command executions. The database page displays all databsase entries created by custom commands, allowing you to view details on or delete individual entries. +The Custom Command Database is used for persistent storage between custom command executions. The database page displays +all database entries created by custom commands, allowing you to view details on or delete individual entries. @@ -11,43 +12,50 @@ The Custom Command Database is used for persistent storage between custom comman
-**1** Entry ID **2** Created Timestamp **3** Updated Timestamp **4** Expiry Timestamp **5** User ID **6** Key **7** Value **8** Size of Value **9** Delete Entry **10** Page Navigation **11** Search Query **12** Search Bar +**1** Entry ID **2** Created Timestamp **3** Updated Timestamp **4** Expiry Timestamp **5** User ID **6** Key **7** +Value **8** Size of Value **9** Delete Entry **10** Page Navigation **11** Search Query **12** Search Bar
-## Entry ID +## Entries -The ID isassigned by the system and unique within YAGPDB's database. The database page is sorted by descending ID. You may seach for a specific ID using the Search Bar (**11**) with ID query (**10**) +### Entry ID -## Created Timestamp +The ID is assigned by the system and unique within YAGPDB's database. The database page is sorted by descending ID. You +may seach for a specific ID using the **Search Bar** (**11**) with ID **Query** (**10**). + +### Created Timestamp UTC timestamp of when the entry was created. -## Updated Timestamp +### Updated Timestamp UTC timestamp of when the entry was updated. Increasing or setting a database value updates this timestamp. -## Expiry Timestamp +### Expiry Timestamp -UTC timestamp of when the entry will expire. An expired entry will not be retrieved by database funcntions, but **will** still appear on the database page. +UTC timestamp of when the entry will expire. An expired entry will not be retrieved by database functions, but **will** +appear on the database page. -## User ID +### User ID -The user-defined ID of the entry (does not have to be a user's ID, accepts any int64). You may seach for a specific ID using the Search Bar (**11**) with User ID query (**10**) +The user-defined ID of the entry (does not have to be a user's ID, accepts any int64). You may search for a specific ID +using the **Search Bar** (**11**) with User ID **Query** (**10**). -## Key +### Key -The user-defined key of the entry. A key is a string with a 256 character limit. You may seach for a specific key using the Search Bar (**11**) with Key query (**10**) +The user-defined key of the entry. A key is a string, max 256 characters. You may search for a specific key using the +**Search Bar** (**11**) with Key **Query** (**10**). -## Value +### Value The serialized value of the database entry. -## Size of Value +### Size of Value Size of the value in bytes. YAGPDB database entries have a max value size of 100kB. -## Delete Entry +### Delete Entry Deletes the individual entry after confirmation. You may only delete one entry at a time. @@ -61,7 +69,8 @@ Dropdown selection of the type of value to search by. Available options are ID, ## Search Bar -Number or Text to match against database entries. Results will only include entries that exactly match the search pattern. +Number or Text to match against database entries. Results will only include entries that exactly match the search +pattern. When searching for a Key, the search query supports PostgreSQL patterns.