Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:Command Shell"

From Roll20 Wiki

Jump to: navigation, search
(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.2
+
|version=1.3
|lastmodified=2015-06-11}}
+
|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

API ScriptAuthor: manveti
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]
!help
Formally:

S

→ !shell-permission action
command
player


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)
  • write sends message to the chat, preserving whitespace and angle brackets.
  • rawWrite sends message to the chat without preserving any special characters. Useful for writing HTML directly to the chat.
  • writeAndLog is equivalent to write while additionally logging message to the console.
  • writeErr is equivalent to writeAndLog(message, 'gm')
  • sendChat is a wrapper around the built-in sendChat function, which will execute CommandShell-aware API commands.
  • tokenize splits 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