This little guy was born of my desire to have a simple helper process which could be invoked on the fly to perform any number of different tasks. As such, this collection of functions makes it easy to create a process which logs into an XMPP account, I happen to use GTalk’s service, and lays in wait for users to send it commands to perform tasks. Though most of the provided functions aim to satisfy this goal, several key characteristics of the bot are highly configurable. This allows bots to be crated which can do any number other interesting things with its XMPP account; I just can’t happen to think of any at the moment, I’ll leave that up to you if you so desire.

The following documentation will explain each of these steps in detail, but the general way to get up and running is:

• Configure your XMPP connection parameters.
• Load the core namespace into a running JVM instance. I use lein swank from the bot project’s root and connect to the resulting JVM instance via slime. A future goal is to make this standalone.
• Invoke the create-bot function passing all of the inbound message handlers you want associated with your bot instance. For example, to create a bot which processes incoming messages throught the command framework, I simply run the following in my REPL:

  (byob.core/create-bot byob.handlers/command-handler)

• Sit back, sip tea, and command your bot like a boss.

By default, the creation of a bot looks to load the XMPP connection configuration from a classpath resource at resources/xmpp_connection.properties:

(A sample configuration is provided with the bot’s source in resources/xmpp_connection.properties.sample). The bot comes with a library of functions to connect to an XMPP account and listen for incoming commands. When creating a bot, using the create-bot function, the connection described by the “config” variable is used in an attempt to hookup the bot to its XMPP account. By default, the config variable is constructed from the properties described in the resources/xmpp_connection.properties. When the XMPP connection is established, the create-bot function then proceeds to add each of the message handlers provided in the parameter list of the call to create-bot to the bot instance.

Each message sent to a bot is in-turn sent to be processed by each of the bot’s message handlers for processing. A message handler is simply a function which accepts a the XMPP connection and a map representation of a received XMPP message. The message is then processed according to the body of the message handler function.

For example, suppose that when a message is received it would be useful to log the body of the message to the standard output stream. To implement this simply write the following function:

  (defn stdout-handler 
    "Logs the body of a received message to the standard output stream."
    [connection message-map] (println (:body message-map)))

The handler function can be attached to a bot in one of two ways. First, the handler function can be provided to the bot construction method, create-bot, and the handler will be automatically wired into the resulting bot instance:

  ;; Note that create-bot accepts a variable length argument of handler functions, so add as many handlers as you like.
  (create-bot stdout-handler)

or the handler can be added to an existing bot instance by invoking the add-message-handler function; which resides in the xmpp namespace:

  ;; Add the stdout-handler function to the collection of handlers for the bot
  (add-message-handler bot stdout-handler)

The following information is available from the message-map sent into a handler:

At its core, the bot’s command framework is enabled by the command-handler message handler. The command handler simply parses a received message for a known instruction. The command associated with that instruction is then invoked with the arguments supplied in the message. A command is any plain old function. The command-handler uses the commands map from the commands namespace to perform lookups of functions. Let’s walk through an example of creating a new command.

Let’s define a command which returns the date and time according to the server on which the bot is running. First define a function to get the interesting data:

  (defn now 
    "Returns the current server date and time." 
    [] (java.util.Date.))

If added into the commands namespace, this function will automatically be included in the collection of functions known to the command-handler. This is achieved by introspection of the namespace during the definition of the commands variable.

When the command-handler function receives a message body which contains the now command, the now function will be looked up from the commands map and executed. The command-handler performs one more interesting action, it sends the sender of the original message a chat message with the result of the command function invocation.

At its core, this project makes use of the Smack XMPP API library. A bot is simply an instance of an XMPPConnection object. There are many interesting things you can do with the XMPPConnection and therefore with a bot instance; even though this abstraction hides much of the XMPP detail from end users. So get crazy with it.