Plugin writing - Zirak/SO-ChatBot GitHub Wiki

The bot (from hereforth referred to as Caprica Six) can react to interactions in two ways: Via listeners, or via commands (assuming !! is the invocation pattern):

the following is a listener:
!!Should I eat bananas or apples?
and this is a command (the slash is optional):
!!/tell OctavianDamiean echo Stop fucking sheep!

You can see some extended documentation on what's provided The Bot API, util.js and IO.

##Commands## Best shown by example:

//signature
bot.addCommand( commandObject );
//example
bot.addCommand({
    name : 'echo',
    fun  : function ( args ) { return args; },
    description : 'Echo echo echo echo...'
});

//...in the chat....
!!echo ham
@Whoeverthefuckyouare ham
!!help echo
@Whoeverthefuckyouare Echo echo echo echo...

commandObj can have the following properties (of course, it can have more, but these are the useful ones):

  • name - the command's name. Alphanumeric and dashes.
  • fun - callback function, receiving the Message object (will be talked about later)
  • permissions (optional) - An object containing usage & deletion info. Should be populated with a del and use properties, each having any of the following values:
    • "ALL", (default) everyone can execute the operation (remove or use)
    • "NONE", nobody can execute the operation
    • [id0, id1, ...] an array of user ids who can use the command.
  • description (optional) - the command's description, fetched when a user looks it up in help
  • async - whether the command is asynchronous. If it is, its function receives an extra parameter, a callback to be optionally called when it finishes.

Now, the permissions value is probably horribly explained, so here are some examples:

//everybody can use, nobody can delete
permissions : {
    del : 'NONE'
}
//nobody can use, everybody can delete (why would you do that?)
permissions : {
    use : 'NONE'
}
//only users 42 and 1337 can delete, everybody can use
permissions : {
    del : [42, 1337]
}
//everybody can do anything
//either simply omit that property, or:
permissions : {}

##Listeners## Listeners are regular-expressions trying to match the user's input. For instance, to give the horse a lick:

!!give the horse a lick
@Whoeverthefuckyouare Mmm! the horse tastes just like raisin.

And the listener regex looks like this: /^give ([\w\s]+) a lick/

When the bot sees something isn't a command or any other prefix-having functionality, it runs over all the listeners, and when one matches, execute it.

bot.listen( regex, callback );

That adds a callback called whenever the input matches regex. The callback accepts one argument: The Message object (will be discussed later on), with a special matches property, containing the capturing groups of the regex (msg.matches[0] is the whole match, .matches[1] is the first capturing group and so forth.)

##The Message object## Every command and listener receive this as the first argument. It's an object wrapper around the user's message containing useful functions for formatting and replying. It also wraps around whatever object the bot received while getting the input. That object has (or at least should have) information regarding the sender's username, id, the message id and the room it was in.

Without further ado, here's its method list:

  • send(text) - sends text to chat without any additional formatting.
  • reply(text) - sends text to chat as a reply to the triggering user (e.g. in SO chat, @username text)
  • directreply(text) - sends text as a reply to the triggering message (e.g. in SO chat, :msgid text)
  • parse(text, map) - parses text for space-delimited, quote-grouped arguments. this will be discussed in greater detail after this list.
  • exec(regex) - internal, used for listeners
  • findUserId(username) - returns the user-id corresponding to username
  • codify(text) - codifies text
  • escape(text) - escapes text for special characters used in the chat
  • link(text, url) - returns a chat-recognizable link for url, displayed with text (e.g. in SO chat [text](url))

Note: By the time it reaches any command or listener, the original input has been sliced to remove the bot invocation boilerplate.

//if the original message was
!!/echo I love pancakes
//you will see it ass
I love pancakes

###parse###

parse( text, map )

I'd love to go into a description, but I suck. So see the examples here until I can find a way to intelligibly explain it.

Overloads:

  • parse() - parses the original message (the one which triggered the bot)
  • parse(true) - turns every parsed component into its own Message object. Not useful until you really need it.
  • parse(text) - parses text instead of the original message
  • parse(text, true) - combination of the two above options