The help command¶
NioBot comes with a built-in help command, which can be used to display information about other commands.
This built-in command is simple, slick, and most importantly, helpful.
It takes one optional argument, command, which changes the output to display information about a specific command.
Without this, the help command will list every enabled command, their aliases, a short help string, and a short
description about the command (by default, the first line of the docstring).
This allows for you to easily just add commands and not have to worry about documenting them outside of simply defining their usage in the command decorator, and a short description in the docstring.
An example of the help command with no arguments
Source of this sample
This is the output of the help command from nexy7574/niobot-test
?[help|h]: Shows a list of commands for this bot
?[ytdl|yt|dl|yl-dl|yt-dlp] <url> [format]: Downloads a video from YouTube
?[quote|q]: Generate a random quote.
?ping: Shows the roundtrip latency
?info: Shows information about the bot
?cud: Creates, updates, and deletes a message
?upload <type: image|video|audio|file>: Uploads an image
?hello: Asks for an input
?version: Shows the version of nio
?[pretty-print|pp]: Pretty prints given JSON
?eval: Evaluates Python code
Info
There is markdown formatting in the output, but it is not shown here.
An example of the help command with a specified command name
Source of this sample
This is the output of the help command from nexy7574/niobot-test
Info
There is markdown formatting in the output, but it is not shown here.
Registering your own help command¶
If you would like to register your own help command, you need to be aware of the following:
- The help command is a command, much like any other command, and is registered as such. You should be aware of aliases, case sensitivity, command states (e.g. disabled/enabled), etc.
- A help command is almost always a user's first impression of your bot. You should make sure that it works 100% of the time, is insanely simple to use, and is very helpful. A help command that just says "You can use command like ?info" is not helpful at all, and will likely turn many users away.
???+ question Are there any dangers to these help commands?
Help Command functions:¶
clean_output ¶
clean_output(
text: str,
*,
escape_user_mentions: bool = True,
escape_room_mentions: bool = True,
escape_room_references: bool = False,
escape_all_periods: bool = False,
escape_all_at_signs: bool = False,
escape_method: Optional[Callable[[str], str]] = None
) -> str
Escapes given text and sanitises it, ready for outputting to the user.
This should always be used when echoing any sort of user-provided content, as we all know there will be some
annoying troll who will just go @room for no apparent reason every 30 seconds.
Do not rely on this!
This function is not guaranteed to escape all possible mentions, and should not be relied upon to do so. It is only meant to be used as a convenience function for simple commands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text |
str
|
The text to sanitise |
required |
escape_user_mentions |
bool
|
Escape all @user:homeserver.tld mentions |
True
|
escape_room_mentions |
bool
|
Escape all @room mentions |
True
|
escape_room_references |
bool
|
Escape all #room:homeserver.tld references |
False
|
escape_all_periods |
bool
|
Escape all literal |
False
|
escape_all_at_signs |
bool
|
Escape all literal |
False
|
escape_method |
Optional[Callable[[str], str]]
|
A custom escape method to use instead of the built-in one (which just wraps characters in |
None
|
Returns:
| Type | Description |
|---|---|
str
|
The cleaned text |
format_command_name ¶
Formats the command name with its aliases if applicable
format_command_line ¶
Formats a command line, including name(s) & usage.
get_short_description ¶
Generates a short (<100 characters) help description for a command.
get_long_description ¶
Gets the full help text for a command.