CommandSystem

The CommandSystem

Existing commands

All in all, the bot is fully operable only via chat (and actually only via chat).
Commands are invoked with !command.
Some commands have restrictions, like they can only be used in a private chat, only in public chat, or need admin rights.

• add: Adds a new song to the queue.
• clear: Removes all songs from the current playlist.
• eval: Executes a given command or string
• help: Shows all commands or detailed help about a specific command.
• history: Shows recently played songs.
• if: - no description yet -
• kickme: Guess what?
• link: Gets a link to the origin of the current song.
• loop: Gets or sets whether or not to loop the entire playlist.
• next: Plays the next song in the playlist.
• parse: Displays the AST of the requested command.
• pause: Well, pauses the song. Undo with !play
• play: Automatically tries to decide whether the link is a special resource (like youtube) or a direct resource (like ./hello.mp3) and starts it
• pm: Requests a private session with the ServerBot so you can invoke private commands.
• previous: Plays the previous song in the playlist.
• print: Lets you format multiple parameter to one.
• quit: Closes the TS3AudioBot application.
• quiz: Enable to hide the songnames and let your friends guess the title.
• random: Gets whether or not to play playlists in random order.
• repeat: Gets or sets whether or not to loop a single song.
• rng: Gets a random number.
• seek: Jumps to a timemark within the current song.
• song: Tells you the name of the current song.
• stop: Stops the current song.
• subscribe: Lets you hear the music independent from the channel you are in.
• take: Take a substring from a string
• test: Only for debugging purposes
• unsubscribe: Only lets you hear the music in active channels again.
• volume: Sets the volume level of the music.

Basic commands

Command Syntax

Every command is build up by the following scheme

!<commandname> <parameter1> <parameter2> ...

Command matching

The string matcher can still find the correct command for you even if you misspell it. This way

!historyy lastt 10
!his la 10
// or even
!higsndtor latuht 10

for example should all match to

!history last 10

This works by picking the command with the most matching characters. So the last example would match on hi_s__tor lat___ with 6 and 3 characters. Therefore the best match is history and last. But !ahistory last 10 will not match since the algorithm is greedy. The word history with no 'a' will be filtered out inbefore.

Escaping

Since spaces seperate parameters you have to quote a string if it has to contain spaces, like this:

!history rename 123 "New Song Name"

Note that a single quote (without closing quote) will not be interpreted as a control sequence but instead as a normal text character.

!bot name Funky"Name

Will rename the bot to Funky"Name

On the other hand of you want quotes in an already quoted string you can escape them with a backslash.

!bot name "Funky\" \"Name"

Will rename the bot to Funky" "Name

The last characters which need to be within quotes are '(' and ')', since they are used for command chaining (see further below)

!bot name "(sneaky)"

Will rename the bot to (sneaky)

Command Chaining

Chaining syntax

!<level1_1> (!<level2_1> <param2_1> <param2_2>) <param1_2> (!<level2_2> (!<level3_1>)))

A chained subcommand is indicated with (!...); please notice that there must be no space between '(' and '!'

Simple chaining

If you want to combine two command you can easily do that by 'chaining' them. Example:

!history play (!rng 0 100)

This will play a random song from the history by an id between 0 and 100.

###Execution order The system will by default execute commands lazily from left to right. Lets take a look at at this simple example

!print (!list load .queue) (!list show)

We start at !print but print has two parameter which have to be executed first. We start at the first !list load .queue which only has two static parameter, so it can be executed. Now the second parameter !list show which -again- has only one static parameter and can be executed. Now all parameter of !print have been evaluated and print can be run.
So this chained command actually loads the playlist named '.queue' and shows the content in one call.

Here's a bit more complex example:

!if (!rng 1 10) == 6 (!kickme (!if (!rng 1 2) == 1 near far)) (!print "You're lucky")

We start at the !if command, before the if command executes, we need to look at the parameter. The first parameter is (!rng 1 10) which itself has two static parameter and can be executed. Then the second and third parameter are static, == and 6. Lets say we got a '6' from the rng so the 'true' branch will be executed. The next command therefore is !kickme. kickme can have an optional parameter so the first parameter has to be executed before we can continue in kickme. !if will now execute by the same scheme as the 'big if' and either return near or far which will then be passed to kickme.

###Parenthesis ommiting

!print My first number: (!rng 0 100) My second number (!rng 0 100

All closing brackets can be omitted. Unless you need them semantically like in the example.

On the other hand you can add superfluous closing brackets as much as you want. The will simply be ignored.