Syntax & Aliases

This document describes how commands are called, and how you can customize the bot's behavior in regards to how commands are called.

Case

The commands should be case insensitive. If you find one that isn't, please report it, because then it's a bug.

Syntax descriptions

<> means a parameter is mandatory

_ _ means a parameter is optional

* * means a parameter is optional and may be repeated

+ + means a parameter is mandatory and may be repeated

Command prefix

A command is called by using a certain prefix in front of the command name. By default this prefix is !, but it may be changed at will. For example, some kd's prefer to use . instead, and that's fine, just set it in the bot's properties.

General form

<command prefix><command name> <command parameters>

Not all commands have any parameters however.

Example: !calc 1+1

Example: !aid

Names & Categories

For some commands you can specify names or categories. For example, for Orders you may specify an Order Category, and for Builds you may specify a name for the build. Names and categories are specified with (). So, if you've added an order category called Army, you could do !addorder (Army) hi, this is an army command.

Common parameters

Not all commands have examples in their syntax descriptions, so below is a list of the form of the various command parameters that are mentioned in the syntax descriptions.

id

Any type of id is just a regular integer number. You may use a comma as a seperator if you'd like, but not spaces. I.e. 5,245 is ok, but 5 425 is not.

utodate

Any type of uto dates may use both the old and new forms, so May 23rd, YR8 is ok just like May 23, YR8.

real life datetime

When it comes to specifying real life datetimes, the format is based on the ISO standard, but without the seconds. So, for example: 2012-08-12 18:05 is a valid date and time.

bindings

See the wiki page on Bindings

filters

See the wiki page on Filters

kd locations

(1:1) is valid, 1:1 is not (at least at the moment)

various numbers

Usually it's ok to use decimal numbers in most places, but in some cases decimal numbers make no sense (like say if you want to limit a result for the !find command, you can't get 3.67 results). Sometimes an integer means an amount of some sorts, while a decimal number refers to hours. Sometimes it's also ok to use the "k-syntax", meaning inputting something like 45.8k to signify 45800. In the cases where there's any doubt on what's permissible, the syntax description should provide examples (please point out these cases when you run into them).

all

In some commands you may be allowed to specify that you want "all" results to be shown, even ones that might be hidden otherwise. It may also be the case that you want to use it like a wildcard, for example to include all different types of spells in your request, rather than just say Fireball. Either way, when the "all" word is referred to in a syntax description, the symbol you use is *

NOTE TO SELF: add more descriptions here

Aliases

In the old bots you could add simple aliases to commands. An example of this was the !calc command, which had !c as an alias, meaning they both meant the same thing. The same command would be called. Starting from version 3.0 the alias concept has been changed. Commands don't have aliases anymore, rather the aliases are completely separate from commands.

An alias now works as a standalone input transformer. A few examples should help explain this concept:

Example 1

Use case: User A wants to type !ad instead of !admins. This is an example of an alias for a command with no parameters.

Example:

1. Alias: !ad
2. Transform: !admins

Result: ad and admins can now be used interchangably.

Example 2

Use case: User A is too lazy to type out !find [>1kk gc, 1000-1200 land, <24 age, !Faery, !Halfling] every time he wants to search for targets to steal gcs from. This example is about pre-filling values for a command.

Example:

1. Alias: !fgc
2. Transform: !find [>1kk gc, 1000-1200 land, <24 age, !Faery, !Halfling]

Result: every time the bot sees someone write !fgc the bot will see it as what's in the transform instead.

Example 3

Use case: User A has written a funny script for the bot that makes the bot hand out cookies to the user calling the command. The command would normally be called through !cookiesplz, but having it as a formal command like that takes away the fun a bit. This is an example of using some free text instead of a command with a suffix.

Example:

1. Alias: gieb cookies plz!
2. Transform: !cookiesplz

Result: the bot will hand out cookies when someone writes gieb cookies plz!

Example 4

Use case: User A is just way too used to using !cb instead of !sot and wants to keep up that habit. This is an example of aliasing a command that sometimes is used with parameters (province name for example), but can also be used without it (just getting the current users intel).

Example: 1. Alias: !cb(?: (.+))? 2. Transform: !sot {1}

Result: cb and sot can now be used interchangably.

Example 5

Use case: User A wants to use !c instead of !calc, because he is lazy. This is an example of aliasing a command that always has some type of parameter (!calc does not work unless you write something to calculate too).

Example: 1. Alias: !c (.+) 2. Transform: !calc {1}

Result: c and calc can now be used interchangably.

Notes

The above examples should cover a large part of what any reasonable user would use aliases for. Basically you'd just pick the example matching your situation and switch out the command name etc. and leave the expressions and such alone.

Import to note from the examples:

1. Aliases are NOT personal. They apply for everyone
2. Aliases do not have to use the command prefix
3. Aliases are applied before the bot does anything in trying to recognize what the input actually means. I.e. if you choose the alias poorly, you could end up making a command impossible to use
4. If you change the command prefix (for example using . instead of !), you'll need to change your aliases too, since the aliases are completely unaware of what prefixes even are