Difference between revisions of "Script:Command Shell"
From Roll20 Wiki
(Document sendChat wrapper added in v1.2) |
(Update docs for v1.3) |
||
| Line 2: | Line 2: | ||
|name=CommandShell | |name=CommandShell | ||
|author={{user profile|503018|manveti}} | |author={{user profile|503018|manveti}} | ||
| − | |version=1. | + | |version=1.3 |
| − | |lastmodified=2015- | + | |lastmodified=2015-07-09}} |
'''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. | '''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. | ||
| Line 79: | Line 79: | ||
=== Changelog === | === Changelog === | ||
| + | {{changelog version|1.3|2015-07-09|* Pass speakingAs through to handlers in wrapped sendChat}} | ||
{{changelog version|1.2|2015-06-11|* Add wrapper for sendChat which can execute CommandShell-aware API commands}} | {{changelog version|1.2|2015-06-11|* Add wrapper for sendChat which can execute CommandShell-aware API commands}} | ||
{{changelog version|1.1|2015-05-31|* Fix argument parsing when final token is quoted}} | {{changelog version|1.1|2015-05-31|* Fix argument parsing when final token is quoted}} | ||
{{changelog version|1.0|2015-01-07|* Initial release}} | {{changelog version|1.0|2015-01-07|* Initial release}} | ||
Revision as of 02:49, 10 July 2015
Version: 1.3
Last Modified: 2015-07-09
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 |
Syntax
By default, commands may only be executed by a GM. The !shell-permission command is provided to set permissions to allow or deny execution by other players, while the !help command may be used to list all available commands. By default, the !help command has world-execute permission, but that permission can be revoked like any other command.
!shell-permission <action> <command name> [player]
!helpFormally:
S→ !shell-permissionactioncommandplayer
S→ !help
action→ add
action→ remove
command→ string
player→ ε
player→ string
| Parameter | Values |
|---|---|
| action | Valid values are add and remove. This will add or remove permission for a specified player (or all players, if no player is specified) to use the given command. World-execute permission is stored separately from player-specific permission, so if world-execute permision is revoked, any player-specific permissions will remain.
|
| command name | The name of the command to alter permissions for. The command given must be registered to the shell. (See below) |
| player | Optional. If set, the permission for the given player will be added or removed for the given command. If omitted, world-execute permission will be changed instead. |
Registering Commands
Each usable command in a script needs to be registered in code somewhere. Commands may also be unregistered.
Registered commands 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.
Shell.registerCommand(command, signature, description, callback)
Shell.unregisterCommand(command)
Parameters
- command
- The command name. Multiple commands of the same name may not be registered. Scripts may include or omit the leading exclamation mark; the shell will handle its requirement automatically.
- signature
- Example syntax of the command (e.g.
"!mycommand [some arguments]"). This will be used in the automatically-generated help output. - description
- A more detailed description of the command and how to use it. This will be used in the automatically-generated help output.
- callback
- The function which will be called whenever the command is invoked by a user with appropriate permission. The function should accept an array of the command arguments (e.g.
["!mycommand", "foo", "bar"]) and the original chat message object.
Utility Functions
Several utility functions are also made available by the shell.
Shell.write(message[, to[, style[, from]]])
Shell.rawWrite(message[, to[, style[, from]]])
Shell.writeAndLog(message[, to])
Shell.writeErr(message)
Shell.sendChat(speakingAs, input)
Shell.tokenize(message)
-
writesends message to the chat, preserving whitespace and angle brackets. -
rawWritesends message to the chat without preserving any special characters. Useful for writing HTML directly to the chat. -
writeAndLogis equivalent towritewhile additionally logging message to the console. -
writeErris equivalent towriteAndLog(message, 'gm') -
sendChatis a wrapper around the built-insendChatfunction, which will execute CommandShell-aware API commands. -
tokenizesplits the given string around whitespace; quotes within the message may be used to preserve the whitespace. Useful for splitting an input message into command arguments.
Parameters
- message
- A message to output or parse
- to
- Player or character to send message to. If not specified, the message will be visible to everyone.
- style
- Inline CSS to include in the <div> that wraps the message.
- from
- Used as first argument to
sendChat. If not specified, the name "Shell" will be used instead.
Changelog
v1.3 (2015-07-09)
- Pass speakingAs through to handlers in wrapped sendChat
v1.2 (2015-06-11)
- Add wrapper for sendChat which can execute CommandShell-aware API commands
v1.1 (2015-05-31)
- Fix argument parsing when final token is quoted
v1.0 (2015-01-07)
- Initial release
