Latest revision as of 12:21, 30 November 2022

Page Updated:   2022-11-30

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).

[edit] 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

[edit] 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)

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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