1.0.0
REFACTOR_NOTE.md
createCommand("foo")
.addArgument(args => args.number.setName("bar").positive())
!man !help
will now resolve to the help command aswell)NOT_FOUND_MESSAGE
to "1"
getCommandByName
to CommandCollectorgetAvailableCommands
to CommandCollectorIn order to load this library you need to wait for the load event.
After this you can import the library with require("command")
const engine = require("engine")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
//start declaring your Commands from here
engine.log(`Command prefix is ${command.getCommandPrefix()}`)
})
This command lets some defined clients use the command !come which will move the Sinusbot to the channel of the requesting User
const backend = require("backend")
//uids which are allowed to use this command
const allowed = [
"NF61yPIiDvYuOJ/Bbeod84bw6dE=",
"Dtrx9Cf5tRP81P4gKnc3ttLo6Kk="
]
const backend = require("backend")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
//creates the command "come"
command.createCommand("come")
//sets a helptext, this gets displayed when using the command help
.help("moves the sinusbot to your channel")
//sets a manual command
.manual("This will let Sinusbot join into your channel")
//checks if the client is allowed to use this command
//the function receives the requesting client as single parameter
//the function should return true if the client is allowed to use this command
//BEWARE this function gets called on every help command and everytime the client tries to execute the command
//so this function should not have any CPU/IO intense tasks
.checkPermission(client => {
//returns true when the client is in the list of allowed clients
return allowed.includes(client.uid())
})
//this function gets executed when a command has been parsed successfully
//the arguments which this function receives are following:
//1) the client which has executed the command
//2) the arguments which had been parsed
//3) reply, depending on where the client has sent the message it will automatically reply to the client, channel or server chat
//4) the raw text of the message
.exec((client, args, reply, raw) => {
const channel = client.getChannels()[0]
if (channel === undefined) return reply("Channel you are in has not been found!")
backend.getBotClient().moveTo(channel)
})
})
This command will send one or more pongs to the clients
Command.createCommand("ping")
//sets a helptext, this gets displayed when using the command help
.help("replies n times with Pong!")
//sets a manual command this
.manual("replies at least one time with ping")
//the second manual command will add it as new line
//looks better than having an ultra long string
.manual("depending on the number given it will replies with this amount of pongs")
//creates a number argument with the name "amount" a number of 1 to 10 is allowed
.addArgument(args => args.number.setName("amount").min(1).max(10).optional(1))
//this function gets executed when a command has been parsed successfully
//the arguments which this function receives are following:
//1) the client which has executed the command
//2) the arguments which had been parsed
//3) reply, depending on where the client has sent the message it will automatically reply to the client, channel or server chat
//4) the raw text of the message
.exec((client, { amount }, reply, raw) => {
Array(amount).fill().forEach(() => reply("Pong!"))
})
This command will send the defined message via chat or poke to all clients
const backend = require("backend")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
//creates the command mass
command.createCommand("mass")
//sets a helptext, this gets displayed when using the command help
.help("sends a mass chat or poke to all clients")
//sets a manual command this
.manual("Usage: ${Command.getCommandPrefix()}mass <chat|poke> <message>")
//allows the word "chat" or "poke" as second argument
.addArgument(args => args.string.setName("action").whitelist(["chat", "poke"]).toLowerCase())
//parsed the rest of the string, it should have a minimum length of 3
.addArgument(args => args.rest.setName("message").min(3))
//this function gets executed when a command has been parsed successfully
//the arguments which this function receives are following:
//1) the client which has executed the command
//2) the arguments which had been parsed
//3) reply, depending on where the client has sent the message it will automatically reply to the client, channel or server chat
//4) the ev text of the message
.exec((client, args, reply, ev) => {
let sent = 0
const ignoreUids = [client.uid(), backend.getBotClient().uid()]
backend.getClients().forEach(client => {
if (ignoreUids === client.uid()) return
sent++
if (args.action === "poke") {
client.chat(args.message)
} else {
client.poke(args.message)
}
})
reply(`Message has been sent to ${sent} Clients!`)
})
})
const backend = require("backend")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
command.createCommand("greet")
.help("sends greetings to the given client")
.manual("This will send a message to the given client on the server")
.addArgument(args => args.client.setName("uid"))
.exec((client, args, reply, raw) => {
const receiver = backend.getClientByUID(args.uid)
if (!receiver) return reply(`No online client with uid ${args.uid} found!`)
receiver.chat(`${client.nick()} sends you his greetings!`)
reply(`Greetings sent to ${receiver.nick()}`)
})
})
//create a function which uses asynchronous functions
function wait(time) {
return new Promise(fulfill => {
setTimeout(fulfill, time)
})
}
const backend = require("backend")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
//creates the command "async"
command.createCommand("async")
//sets a helptext, this gets displayed when using the command help
.help("tests the aync execution")
//this function gets executed when a command has been parsed successfully
//the arguments which this function receives are following:
//1) the client which has executed the command
//2) the arguments which had been parsed
//3) reply, depending on where the client has sent the message it will automatically reply to the client, channel or server chat
//4) the raw text of the message
//in order to use async functions and have correct error handling within the command.js usage do it like this
.exec((client, args, reply, raw) => {
//return an instance of promise
return new Promie(async (fulfill, reject) => {
try {
await wait(1000)
//resolve the function successfully
fulfill()
} catch (e) {
//reject the function when an error occured
reject(e)
}
})
})
})
Want to parse the arguments by yourself?
//creates the command arg
command.createCommand("arg")
//sets a helptext, this gets displayed when using the command help
.help("example which outputs the given additional arguments")
//this will catch all arguments
.addArgument(args => args.rest.setName("args").optional(""))
//this function gets executed when a command has been parsed successfully
//the arguments which this function receives are following:
//1) the client which has executed the command
//2) the arguments which had been parsed
//3) reply, depending on where the client has sent the message it will automatically reply to the client, channel or server chat
//4) the raw text of the message
.exec((client, { args }, reply) => {
//the variable args will now hold all the parameters which have additionally been added after the command
reply(`Your arguments are ${args}`)
})
This will create a command with multiple sub commands. For example to implement a command which handles money !money add 10 !money remove 5
const backend = require("backend")
const event = require("event")
//this makes sure that all scripts have finished loading
event.on("load", () => {
//try to load the library
const command = require("command")
//check if the library has been loaded successfully
if (!command) throw new Error("command.js library not found! Please download command.js and enable it to be able use this script!")
//this will return an instance of the GroupCommand class
//most methods from the Command class are available here also
const moneyCommand = Command.createCommandGroup("money")
//sets a helptext, this gets displayed when using the command help
.help("manages the money of users")
//you can use exec here aswell but you are not able to add any Arguments!
//the addCommand method will create a new instance of the SubCommand class
//this class is basically the same as the basic Command class
//if a user sends `!money add x` then this command gets executed
moneyCommand.addCommand("add")
.help("Adds a certain amount of money to you")
.addArgument(args => args.number.setName("amount").min(1))
.exec((client, args, reply) => {
//add money to the user
})
//you can create multiple sub commands when calling again addCommand on the commandGroup class
//if a user sends `!money remove x` then this command gets executed
moneyCommand.addCommand("remove")
.help("Removes a certain amounf of money from you")
.addArgument(args => args.number.setName("amount").min(1))
.exec((client, args, reply) => {
//remove money from a user
})
})
Definition for Classes
Retrieves the usage of the command with its parameterized names
any
:
retrieves the complete usage of the command with its argument names
checks if a client should have permission to use this command
(Client)
the client which should be checked
adds an argument to the command
((createArgumentHandler | Argument))
an argument to add
retrieves all available arguments
(string)
(MessageEvent)
Retrieves the usage of the command with its parameterized names
any
:
retrieves the complete usage of the command with its argument names
checks if a client should have permission to use this command
(Client)
the client which should be checked
(string)
(MessageEvent)
Type: Array<execHandler>
(string)
(MessageEvent)
checks if the command is enabled
enables the current command
disables the current command
gets the command name without its prefix
retrieves all registered alias names without prefix
gets the command name with its prefix
retrieves all registered alias names with prefix
retrieves all registered command names
retrieves all registered command names with prefix
retrieves the help text
returns a boolean wether a help text has been set or not
retrieves the current manual text
returns a boolean wether a help text has been set or not
gets the current prefix for this command
clears the current manual text
register an execution handler for this command
(execHandler)
gets called whenever the command should do something
register a permission handler for this command
(permissionHandler)
gets called whenever the permission for a client gets checked
checks if a client is allowed to use this command this is the low level method to check permissions for a single command
(Client)
sinusbot client to check permissions from
dispatches a command
(CommanderTextMessage)
creates a new Throttle instance
retrieves the correct reply chat from where the client has sent the message
(Message)
Name | Description |
---|---|
event.mode any
|
|
event.client any
|
|
event.channel any
|
checks the permissions from a set of commands
(Array<BaseCommand>)
(Client)
Promise<Array<BaseCommand>>
:
retrieves all available permissions for a certain client
(Client)
Searches for one or multiple enabled commands with its prefix
(string)
the command with its prefix
Array<BaseCommand>
:
returns an array of found commands
checks if the command string is save to register as a new command this function basically checks if there is no other command named with throws an error when Collector#validateCommandName errors returns false when this command has been already registered returns true when this is a completely unused command
(string)
Reduces the given points for a Command for the given Client
(Client)
the client which points should be removed
Checks if the given Client is affected by throttle limitations
(Client)
the TeamSpeak Client which should get checked
retrieves the time in milliseconds until a client can send his next command
(Client)
the client which should be checked
any
:
returns the time a client is throttled in ms
Available Argument Types which can be added to a Command
Sets an Argument as optional if the argument has not been parsed successful it will use the first argument which has been given inside this method
(any?)
the default value which should be set if this parameter has not been found
(boolean?
= true
)
wether it should display the default value when called with the #getUsage method
retrieves the default value if it had been set
checks if the Argument has a default value
gets the manual of a command
checks if the Argument is optional
Sets a name for the argument to identify it later when the command gets dispatched This name will be used when passing the parsed argument to the exec function
Class representing a ClientArgument this Argument is capable to parse a Client UID or a simple UID inside the exec function it will resolve the found uid
adds an argument to the command
((createArgumentHandler | Argument))
an argument to add
all callbacks existing
callback for the command event
Type: Function
(Client)
callback for the command event
Type: Function
(ArgType)
Argument
:
callback for the command event
Type: Function
type declarations
Type: object
(StringArgument)
(NumberArgument)
(ClientArgument)
(RestArgument)
(GroupArgument)
(GroupArgument)
These Functions gets exported as object when imported through require("command.js")
(string)
the command which should be added
Command
:
returns the created Command
(string)
the command which should be added
CommandGroup
:
returns the created CommandGroup instance
(any)
Argument
:
returns the created Argument
(("or"
| "and"
))
the argument type which should be created either "or" or "and" allowed
GroupArgument
:
returns the created Group Argument
string
:
returns the command prefix
string
:
returns the semantic version of this script
Throttle
:
returns the created Throttle
Type: string
Type: Client