Fork me on GitHub

Getting Started

Blather comes with a DSL that makes writing XMPP bots quick and easy:

require 'rubygems'
require 'blather/client'

setup 'echo@jabber.local', 'echo'

# Auto approve subscription requests
subscription :request? do |s|
  write s.approve!
end

# Echo back what was said
message :chat?, :body do |m|
  write m.reply
end

Handlers

Handlers let Blather know how you'd like each type of stanza to be well.. handled. Each type of stanza has an associated handler which is part of a handler hierarchy. In the example above we're handling message and subscription stanzas.

XMPP is built on top of three main stanza types (presence, message, and iq). All other stanzas are built on these three base types. This creates a natural hierarchy of handlers. For example a subscription stanza is a type of presence stanza and can be processed by a subscription handler or a presence handler. If you've done any DOM programming you'll be familiar with this.

Incoming stanzas will be handled by the first handler found. Unlike the DOM this will stop the handling bubble unless the handler returns false.

The entire handler hierarchy can be seen on the handlers page.

Example:

Here we have a presence handler and a subscription handler. When this script receives a subscription stanza the subscription handler will be notified first. If that handler doesn't know what to do it can return false and let the stanza bubble up to the presence handler.

# Handle all presence stanzas
presence do |stanza|
  # do stuff
end

# Handle all subscription stanzas
subscription do |stanza|
  # do stuff
end

Command Line Arguments

Without specifying a setup in the script the default command line arguments are:

Usage: [blather_script] [options] JID password [host] [port]
-D, --debug         Run in debug mode
-d, --daemonize     Daemonize the process
--pid=[PID]         Write the PID to this file
--log=[LOG]         Write stdout/stderr to the [LOG] file
-h, --help          Show this message
-v, --version       Show version