Roll20 Wiki

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

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

@@ Line 2: / Line 2: @@
 |name=CommandShell
 |author={{user profile|503018|manveti}}
-|version=1.0
+|version=1.3
-|lastmodified=2015-01-07}}
+|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.
 It is recommended that this script be used in conjunction with the [[Script:IsGM Auth Module|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).
+=== Syntax ===
+By default, commands may only be executed by a GM.  The <code>!shell-permission</code> command is provided to set permissions to allow or deny execution by other players, while the <code>!help</code> command may be used to list all available commands. By default, the <code>!help</code> command has world-execute permission, but that permission can be revoked like any other command.
+{{syntaxbox top|CommandShell|formal=true}}
+{{API command|shell-permission}} {{API parameter|name=action}} {{API parameter|name=command name}} {{API parameter|name=player|optional=true}}<br>
+{{API command|help}}
+{{Formal API command|
+{{token|S}} {{rarr}} {{API command|shell-permission}} {{token|action}} {{token|command}} {{token|player|-}}
+{{token|S}} {{rarr}} {{API command|help}}
+{{token|action}} {{rarr}} add<br>
+{{token|action}} {{rarr}} remove<br>
+{{token|command}} {{rarr}} {{string|-}}
+{{token|player}} {{rarr}} {{epsilon}}
+{{token|player}} {{rarr}} {{string}}
+}}
+{{syntaxbox end}}
+{{param description top}}
+{{param description|name=action|value=Valid values are <code>add</code> and <code>remove</code>. 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.}}
+{{param description|name=command&nbsp;name|value=The name of the command to alter permissions for. The command given must be registered to the shell. (See below)}}
+{{param description|name=player|value=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.}}
+{{param description bottom}}
 === Registering Commands ===
-Commands are registered via the <code>Shell.registerCommand()</code> function, which takes
+Each usable command in a script needs to be registered in code somewhere. Commands may also be unregistered.
-the following arguments:
-{| border="0"
-|- valign="top"
-|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.
-|- valign="top"
-|signature
-|A string displaying how the command is used (e.g. <code>!mycommand [some arguments]</code>).  This will be used in the automatically-generated help output (the <code>!help</code> command).
-|- valign="top"
-|description
-|A more detailed description of the command and how to use it.  This will be used in the automatically-generated help output.
-|- valign="top"
-|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. <code>["!mycommand", "foo", "bar"]</code>) and the original command string (e.g. <code>"!mycommand foo bar"</code>).
-|}
-If you wish to remove a registered command, call <code>Shell.unregisterCommand(name)</code>.  The specified name must be the name used when the command was registered.
+Registered commands can be executed by name (e.g. <code>!mycommand</code>).  If a user attempts to execute a command for which they lack permission, they will receive an error message and execution will fail.
+{{syntaxbox top|nocat=true}}
+Shell.registerCommand(''command'', ''signature'', ''description'', ''callback'')<br>
+Shell.unregisterCommand(''command'')
+{{syntaxbox end}}
-=== Command Permissions ===
+==== Parameters ====
-By default, commands may only be executed by a GM.  A <code>shell-permission</code> command is provided to set permissions to allow or deny execution by other players.  It operates in two modes:
+; command
-{{syntaxbox top|CommandShell}}
+: 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.
-{{API command|shell-permission}} add {{API parameter|name=command name}} {{API parameter|name=player|optional=true}}
+; signature
+: Example syntax of the command (e.g. <code>"!mycommand [some arguments]"</code>). 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. <code>["!mycommand", "foo", "bar"]</code>) and the original chat message object.
+=== Utility Functions ===
+Several utility functions are also made available by the shell.
+{{syntaxbox top|nocat=true}}
+Shell.write(''message''[, ''to''[, ''style''[, ''from'']]])<br>
+Shell.rawWrite(''message''[, ''to''[, ''style''[, ''from'']]])<br>
+Shell.writeAndLog(''message''[, ''to''])<br>
+Shell.writeErr(''message'')<br>
+Shell.sendChat(''speakingAs'', ''input'')<br>
+Shell.tokenize(''message'')
 {{syntaxbox end}}
-: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.
-{{syntaxbox top|CommandShell}}
-{{API command|shell-permission}} remove {{API parameter|name=command name}} {{API parameter|name=player|optional=true}}
-{{syntaxbox end}}
-: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 ===
+* <code>write</code> sends ''message'' to the chat, preserving whitespace and angle brackets.
-Commands which were registered via registerCommand can be executed by name (e.g. <code>!mycommand</code>).  If a user attempts to execute a command for which they lack permission, they will receive an error message and execution will fail.
+* <code>rawWrite</code> sends ''message'' to the chat without preserving any special characters. Useful for writing HTML directly to the chat.
+* <code>writeAndLog</code> is equivalent to <code>write</code> while additionally logging ''message'' to the console.
+* <code>writeErr</code> is equivalent to <code>writeAndLog(message, 'gm')</code>
+* <code>sendChat</code> is a wrapper around the built-in <code>sendChat</code> function, which will execute '''CommandShell'''-aware API commands.
+* <code>tokenize</code> 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.
-This module provides a <code>help</code> 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 <code>!shell-permission remove help</code>).  Each user will only see the commands which they have permission to execute.
+==== 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 &lt;div&gt; that wraps the message.
+; from
+: Used as first argument to <code>sendChat</code>. If not specified, the name "Shell" will be used instead.
-=== Utility Functions ===
+=== Changelog ===
-The following utility functions are provided for convenience:
+{{changelog version|1.3|2015-07-09|* Pass speakingAs through to handlers in wrapped sendChat}}
-:<code>write(s, to=null, style=null, from=null)</code>
+{{changelog version|1.2|2015-06-11|* Add wrapper for sendChat which can execute CommandShell-aware API commands}}
-::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 <code>sendChat</code> call, otherwise it will be "Shell".
+{{changelog version|1.1|2015-05-31|* Fix argument parsing when final token is quoted}}
-:<code>rawWrite(s, to=null, style=null, from=null)</code>
+{{changelog version|1.0|2015-01-07|* Initial release}}
-::As write, but does not escape angle brackets.  Use this to write HTML.
-:<code>writeAndLog(s, to=null)</code>
-::Calls write(s, to) and logs each line of s to the API console.
-:<code>writeErr(s)</code>
-::Shorthand for <code>writeAndLog(s, "gm")</code>.
-:<code>tokenize(s)</code>
-::Splits the string s into an array based on whitespace.  Quotes preserve spaces, and adjacent quotes are merged (as with POSIX shell command parsing).

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Script:Command Shell"

From Roll20 Wiki

Revision as of 02:49, 10 July 2015

Contents

Syntax

Registering Commands

Parameters

Utility Functions

Parameters

Changelog