Note: This documentation is unfinished. The module itself is still undergoing some design changes. As I update I will try to keep the documentation updated as well, but sometimes lag behind. Feel free to open a pull request if you would like to contribute to the module or the readme.
Later edit: Wow, how long did I spend on this documentation? I never even documented the files... Oh well, they're documented now.
Usage
The module exports properties are equivalent to the names of the classes listed below.
``javascript
const FrozorCommands = require('frozor-commands');
FrozorCommands.Command // The command class
FrozorCommands.CommandArg // The command arg class
FrozorCommands.CommandHandler // the command handler class
// etc
`
$3
#### Description
Use this class to populate your command's arguments array. Type is not validated, but is useful for users.
* name: the name of the command arg (required)
* type: the type of the command arg (optional)
* required: whether the command arg should be required (default true),
* hide: whether the command arg should be hidden (default false)
#### Methods
#### getVariableArgs (Static)
Returns an array of CommandArg instances based on the call parameters (count, name, type, required).
The first instance will be not hidden, and will have [] after the type to show that there may be multiple (or type will be equal to [] if none is set)
This is intended to be used if the user can input CommandArgs where 1 <= args.length <= n
Example:
`javascript
class EchoCommand extends Command{
constructor(){
super({
name: 'echo',
// Aliases is optional, but I'm including it just for my own sanity.
aliases: [],
description: 'Echoes stuff back to you!',
args: CommandArg.getVariableArgs(50, 'text', 'String', true)
})
}
run(msg, client){
/*
* Because required was set to true above,
* there must be at least 1 element for the
* 'text' arg, and up to 50.
*/
let input = msg.args.join(' ');
msg.reply(Here's what you wrote: ${input});
}
}
`
This can, of course, be used in conjunction with other arguments, but generally this should be the last argument in your array.
class SayHello extends Command{
constructor(){
// Here we use ES6 spread syntax to avoid having to use .concat, but concat works too.
super({
name: 'echo',
description: 'Say hi to the client!',
args: [new CommandArg('user_name', 'String', true), ...CommandArg.getVariableArgs(50, 'text', 'String', false)]
})
}
run(msg, client){
/*
* Because required was set to false above,
* there can be between 0 and 50 text args.
* we can check args.length to see how many
* there are, or based on the command it could
* just be ignored.
*/
let name = msg.args[0];
// Set mention to false here so it doesn't mention them
msg.reply(Hey there, ${name}}, false);
}
}
`
#### getUsageString
Returns a string based on whether the arg is hidden, its type, and if it is required.
Required commands have arrow brackets (<>) around them, optional ones have square brackets ([]) around them.
Example return value for optional with type String and name text: [String text]
Example return value for required with type String and name text:
#### parseArgs
Takes an array of strings as its input, and returns an object based on parsed arguments in an array.
If you only have a string/message text and want to parse it, the following can be used to get a message's args: msg.text.split(' ').filter((m)=> m.trim() !== '');. This prevents users from accidentally entering blank spaces as arguments, for instance on mobile.
Properties can be represented in a few ways
* key=value
* key="value with spaces"
* --key value
* --key value with spaces
For instance:
['--prop', 'hello', 'world', 'how', 'are', 'you'] will return {prop: 'hello world how are you'}
['prop="', 'hello', 'world', 'how', 'are', 'you"'] will return {prop: 'hello world how are you'}
Dash properties without a key will be set to true.
['--prop', '--prop2'] will return {prop: true, prop2: true}
key=value properties that attempt to include spaces without quotation marks will be set to the value before the first space. If there is no closing quotation, it will also be set to the first value before the space.