====== commands ======

The commands global table provides access to the bot commands system.

===== getPrefix =====

The getPrefix field contains a function that returns the string that should appear at the start of a chat message for it to be treated as a command invocation.

While this prefix string check is handled for you for commands you register, this function is provided in case you want to ignore command messages in a raw message handler.

==== Syntax ====

  getPrefix(): (prefix: string)

==== Arguments ====

//This function does not expect any arguments.//

==== Returns ====

  - The first return value will be the command prefix.

===== register =====

The register field contains a function that provides the ability to add new commands.

==== Syntax ====

  register(command: table): ()

==== Arguments ====

  - The first argument should contain a descriptor table of the command to be registered. The formatting of this table is described below.

==== Returns ====

//This function does not return any values.//

===== Command descriptor =====

The first argument to the register function expects a Lua table with any of the following fields.

==== name ====

The name field should contain the single name string for a command. This field is **required unless the names field is specified**, in which case the function will raise an error if both are specified. If aliases are required, use the names field instead.

=== Examples ===

  * ''%%name = "test"%%''
  * ''%%name = sense.info.name%%''

==== names ====

The names field should contain a sequential table containing strings to be used as valid aliases for this command. The first in the list will be used as its canonical name. This field is **required unless the name field is specified**, in which case the function will raise an error if both are specified.

=== Examples ===

  * ''%%names = { "water", "h2o" }%%''
  * ''%%names = { "beans" }%%'', it is totally possible and acceptable to use this syntax to only specify a single name.

==== summary ====

The summary field may contain an optional string value to describe what this command will do. The string is displayed in the runtime-provided ''help'' command. While this field is optional, you will be berated if it is left empty for a command that isn't hidden.

=== Examples ===

  * ''%%summary = "This commands sends your usage data to Microsoft."%%''
  * ''%%summary = sense.info.description%%''

==== hidden ====

The hidden field may contain an optional boolean value to indicate that this command is hidden. If set to ''true'', it will be omitted from the runtime-provided ''help'' command, thus rendering the summary field unused. Omitting this field is equivalent to setting it to ''false''.

=== Examples ===

  * ''hidden = true''
  * ''hidden = false''
  * that's literally every possibility.

==== dispatch ====

The dispatch field must contain a callback handler that will be executed when the command is invoked.

=== Syntax ===

  handler(ctx: table): ()

=== Arguments ===

  - The first argument will contain a [[senses:types:command-context|command context]] type table.

=== Returns ===

//This callback does not expect any return values.//

=== Examples ===

   handler = function(ctx) 
      ctx.send('You sent: ' .. ctx.msg.text .. '!')
   end