Script:Command Shell
From Roll20 Wiki
Version: 1.0
Last Modified: 2015-01-07
Code: CommandShell
Dependencies: None
Conflicts: None
CommandShell is a framework for chat commands, intended to ease their processing and avoid command name collisions. CommandShell provides a central system for registering commands and marshalling chat commands to the appropriate callback, POSIX-style argument parsing, access control, and simple output functions.
It is recommended that this script be used in conjunction with the IsGM Auth Module, which will improve detection of messages coming from the GM. In the absence of that module, a player will only be detected as GM when sending chat as their player name (i.e. not speaking as a character).
Contents |
Registering Commands
Commands are registered via the Shell.registerCommand() function, which takes
the following arguments:
| name | A string specifying the command name (if a command of the same name has already been registered, an error message will be written to the chat and the log and the call will fail). An initial '!' will be added automatically if and only if name did not already begin with one. |
| signature | A string displaying how the command is used (e.g. !mycommand [some arguments]). This will be used in the automatically-generated help output (the !help command).
|
| description | A more detailed description of the command and how to use it. This will be used in the automatically-generated help output. |
| callback | A function which will be called whenever the command is invoked by a user with appropriate permission. The two arguments passed to the callback will be an array of the command arguments (e.g. ["!mycommand", "foo", "bar"]) and the original command string (e.g. "!mycommand foo bar").
|
If you wish to remove a registered command, call Shell.unregisterCommand(name). The specified name must be the name used when the command was registered.
Command Permissions
By default, commands may only be executed by a GM. A shell-permission command is provided to set permissions to allow or deny execution by other players. It operates in two modes:
!shell-permission add <command name> [player]
- This will add permission for the specified player to execute the specified command. If no player is specified, everyone will be allowed to execute it.
!shell-permission remove <command name> [player]
- This will revoke the specified player's permission to execute the specified command. If no player is specified, world-execute permission will be removed, but individual player permissions will remain intact.
Executing Commands
Commands which were registered via registerCommand can be executed by name (e.g. !mycommand). If a user attempts to execute a command for which they lack permission, they will receive an error message and execution will fail.
This module provides a help command which lists all registered commands and gives a brief description of each. By default, all users have permission to execute this command, although that permission can be revoked normally (i.e. by executing !shell-permission remove help). Each user will only see the commands which they have permission to execute.
Utility Functions
The following utility functions are provided for convenience:
write(s, to=null, style=null, from=null)- Writes the string s to chat (or whispers it if to is specified), preserving whitespace and angle brackets. If style is specified, it is added to the style of the div in which s is written. If from is a string, it will be passed as the initial argument to the
sendChatcall, otherwise it will be "Shell".
- Writes the string s to chat (or whispers it if to is specified), preserving whitespace and angle brackets. If style is specified, it is added to the style of the div in which s is written. If from is a string, it will be passed as the initial argument to the
rawWrite(s, to=null, style=null, from=null)- As write, but does not escape angle brackets. Use this to write HTML.
writeAndLog(s, to=null)- Calls write(s, to) and logs each line of s to the API console.
writeErr(s)- Shorthand for
writeAndLog(s, "gm").
- Shorthand for
tokenize(s)- Splits the string s into an array based on whitespace. Quotes preserve spaces, and adjacent quotes are merged (as with POSIX shell command parsing).
